Mutt API

7.7

top ← prev up next →

Mutt API

Ben Greenman

(require mutt)

package: mutt

Racket API for the Mutt email client.

This package does not support Windows.

Goals:

Installing the package configures mutt.
Convenient API for sending emails.

Example:

(require mutt)

(parameterize ([*mutt-default-cc* '("beyonce@jayz.gov")])
(mutt "can you hear me?" #:to "justin@beiber.edu" #:subject "Hello"))

1 Install

Install Mutt through your local package manager.
- On Mac, try brew install mutt
- On Ubuntu, use sudo apt-get install mutt
Run raco pkg install mutt. When prompted, enter your email address and name.
(optional) make further edits to your ~/.muttrc file.

If you delete your ~/.muttrc file, running raco pkg update mutt will rebuild it interactively. Alternatively, the mutt/setup module provides a hook for reconfiguring mutt.

(require mutt/setup)

package: mutt

procedure
(setup-mutt!) → void?

Checks that the mutt utility is available and creates a default ~/.muttrc file if none exists.

This function sends prompts to current-output-port and expects responses on current-input-port.

2 API

procedure
(mutt message
...+
#:to to
[ #:subject subject
#:cc cc
#:bcc bcc
#:attachment attach*]) → boolean?
  message : (or/c path-string? content?)
  to : pre-email*/c
  subject : string? = (*mutt-default-subject*)
  cc : pre-email*/c = (*mutt-default-cc*)
  bcc : pre-email*/c = (*mutt-default-bcc*)
  attach* : attachment/c = (*mutt-default-attachment*)

Send an email to the address(es) to with subject subject and message body message. If message is a filename, the email contains the contents of the file. Otherwise, the email contains the string message.

Send carbon copies to the cc addresses; these are public recipients of the same message. Send blind carbon copies to the bcc addresses; the to address will not see the identity of bccs. Attach the files in the list attach*.

Examples:

> (mutt "sry"
        #:to "tswift@gmail.com"
        #:subject "We Are Never Ever Getting Back Together")
#t
> (mutt "https://www.youtube.com/watch?v=oHg5SJYRHA0"
        #:to "support@comcast.com"
        #:subject "10 Craziest YouTube Fails"
        #:cc "everyone@the.net")
#t

Or, with the at-exp reader:

#lang at-exp racket/base
(require mutt racket/port)
(*mutt-exe-path* "xargs echo ")

(define name "Lizzo")

@mutt[#:to "lizzo@juice.net"
      #:subject "truth"]{
  Greetings @|name|,

  How are you feeling today?}

Changed in version 0.4 of package mutt: Accept rest-args, for at-exp compatibility.
Changed in version 0.5: Accept tree of #:to destination addresses.

procedure
(mutt* message
...+
#:to* to
[ #:subject subject
#:cc cc
#:bcc bcc
#:attachment attach*]) → boolean?
  message : (or/c path-string? content?)
  to : pre-email*/c
  subject : string? = (*mutt-default-subject*)
  cc : pre-email*/c = (*mutt-default-cc*)
  bcc : pre-email*/c = (*mutt-default-bcc*)
  attach* : attachment/c = (*mutt-default-attachment*)

NOTE: This function is deprecated; use mutt, instead.

For each recipient address in to*, send an identical email message and include the same cc’s, bcc’s, and attachments.

Examples:

> (define pilots
    (for/list ([i (in-range 1 22)])
      (format "pilot~a@billboard.com" i)))
> (mutt* "all my friends are heathens"
         #:to* pilots
         #:subject "helpme")
#t

procedure
(email? str) → (or/c #f string)
str : string

Returns #f if str does not match a basic regular expression for email addresses.

Examples:

> (email? "support@racket-lang.org")
"support@racket-lang.org"
> (email? "foo@bar.baz")
"foo@bar.baz"
> (email? "a16_@36.21.asdvu")
"a16_@36.21.asdvu"
> (email? "yo lo@dot.com")
#f

value
pre-email/c : (or/c path-string? string?)

Value that the API can convert to a sequence of email addresses. These are:

strings that pass the email? predicate
files that contain newline-separated email addresses

value
pre-email*/c : (or/c pre-email/c (listof pre-email/c))

Value or sequence that the API can flatten into a sequence of email addresses.

procedure
(in-email* pre*) → (listof email?)
pre* : pre-email*/c

Coerce a sequence of values into a flat list of email addresses. Ignores strings in pre* that do not pass the email? predicate (but prints a warning to current-output-port). Raises an argument error if pre* contains a path that does not exist on the local filesystem.

value
attachment/c : (or/c #f path-string? (listof path-string?))

Contract for an argument that specifies a file (or files) to attach to an email.

2.1 Options and Parameters

parameter
(*mutt-default-subject*) → string?
(*mutt-default-subject* subject) → void?
subject : string?
= "<no-subject>"

Default subject to use in email addresses.

parameter
(*mutt-default-cc*) → (listof email?)
(*mutt-default-cc* addrs) → void?
addrs : (listof email?)
= '()

List of addresses to cc by default.

parameter
(*mutt-default-bcc*) → (listof email?)
(*mutt-default-bcc* addrs) → void?
addrs : (listof email?)
= '()

List of addresses to bcc by default.

parameter
(*mutt-default-attachment*) → (listof path-string?)
(*mutt-default-attachment* files) → void?
files : (listof path-string?)
= '()

List of files to attach by default.

parameter
(*mutt-exe-path*) → (or/c #f path-string?)
(*mutt-exe-path* path) → void?
path : (or/c #f path-string?)
= (find-executable-path "mutt")

Path to your Mutt executable. If #f, calls to mutt will never send emails. This is useful for debugging — set the parameter to #false and subscribe to the mutt-logger at the 'info level to see the system commands that would be invoked.

value
mutt-logger : logger?

A logger that reports events with the topic 'mutt.

3 Typed API

(require mutt/typed)

package: mutt

Typed clients should import the mutt/typed module.

value
mutt
:
(->* [Path-String
      #:to Pre-Email*]
     [#:subject String
      #:cc Pre-Email*
      #:bcc Pre-Email*
      #:attachment (U #f Path-String (Listof Path-String))]
     Boolean)
value
mutt*
:
(->* [Path-String
      #:to Pre-Email*]
     [#:subject String
      #:cc Pre-Email*
      #:bcc Pre-Email*
      #:attachment (U #f Path-String (Listof Path-String))]
     Boolean)
value
in-email* : (-> Pre-Email* (Listof String))
value
email? : (-> String (U #f String))
value
*mutt-default-subject* : (Parameterof String)
value
*mutt-default-cc* : (Parameterof (Listof String))
value
*mutt-default-bcc* : (Parameterof (Listof String))
value
*mutt-default-attachment* : (Parameterof (Listof Path-String))
value
*mutt-exe-path* : (Parameterof Path-String)

Type signatures:

value
Pre-Email : (U String Path-String)
value
Pre-Email* : (U Pre-Email (Listof Pre-Email))

4 FAQ

Q. Can racket-mutt accept certificates on the command line?

No. Run mutt on the command line to manually approve certificates. (Make sure to "always accept" the certificate.)

top ← prev up next →