Mutt API

8.16.0.1

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*
#:reply-to reply-to]) → 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*)
  reply-to : (or/c #f pre-email*/c) = (*mutt-default-reply-to*)

Send email(s) 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*. Set the reply-to address(es), as the default Reply-To target.

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)
;(*mutt-exe-path* "xargs echo ") ;; uncomment for a dry run

(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.
Changed in version 0.6: Added #:reply-to.
Changed in version 0.8: Allow multiple #:reply-to 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-default-reply-to*) → (or/c #f string?)
(*mutt-default-reply-to* reply-to) → void?
reply-to : (or/c #f string?)
= #f

Default Reply-To address.

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))
      #:reply-to (U #f 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-default-reply-to* : (Parameterof (U #f 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.)

Q. Google gmail stopped allowing less-secure apps in May 2022. What to do?

Try OAuth2: https://shallowsky.com/blog/tech/email/gmail-api-oauth2.html

or IMAP: https://domm.plix.at/perl/2022_05_use_multiple_gmail_accounts_via_mutt_and_offlineimap.html