#smtp API reference

An SMTP send client: the line-oriented command/response dialogue of RFC 5321, over the net system library (plaintext, implicit TLS, or STARTTLS) with SASL AUTH: PLAIN, LOGIN, XOAUTH2, CRAM-MD5, and SCRAM-SHA-1 / SCRAM-SHA-256. The message body is any string, typically built by the mime module. Because it uses net, this module runs on the default jennifer binary only (jennifer-tiny stubs the network stack). send (the one-shot convenience) throws a catchable Error (kind "smtp") when the server rejects a command. To deliver a queue of messages over a single TLS + auth handshake, open a persistent Session, sendOn each message, and close. TLS certificate verification is the net default. An IDN host or envelope domain is IDNA-encoded to its xn-- form (via the idna module); a non-ASCII address local part still throws (it needs SMTPUTF8).

Import with import "smtp.j" as smtp;. See the smtp guide for prose and examples.

#Functions

#smtp.close(session as Session)

Close a session: send QUIT (best-effort) and close the socket. Idempotent-safe to call once; do not use the session afterwards.

Parameters

• session {Session} - the session to close

#smtp.open(opts as Options)

Open an authenticated SMTP session: connect per opts.security, read the greeting, EHLO, upgrade with STARTTLS when asked (refusing a server that did not advertise it - anti-downgrade), and authenticate when credentials are present. The returned Session is ready for one or more sendOn calls, so a queue of N messages pays this TLS + auth handshake once instead of N times.

Parameters

• opts {Options} - the connection and auth settings

Returns {Session} - an authenticated, ready session

Throws

• {Error} - kind "smtp" if the connection, greeting, STARTTLS, or auth fails

#smtp.send(opts as Options, from as string, recipients as list of string, message as string)

Deliver message (a full RFC 5322 message, e.g. from mime.encode) to every recipient, with from as the envelope sender - the one-shot convenience: open a session, sendOn this one message, and close. To send several messages over one handshake, call open / sendOn / close yourself.

Parameters

• opts {Options} - the connection and auth settings
• from {string} - the envelope sender address
• recipients {list of string} - the envelope recipient addresses
• message {string} - the full RFC 5322 message body

Throws

• {Error} - kind "smtp" when the server rejects a command or an address is not ASCII-safe

#smtp.sendOn(session as Session, from as string, recipients as list of string, message as string)

Deliver one message (a full RFC 5322 message, e.g. from mime.encode) over an open session: RSET, MAIL FROM / RCPT TO / DATA. The session is reusable afterwards (call sendOn again for the next message; close when done).

Parameters

• session {Session} - an open session (from open)
• from {string} - the envelope sender address
• recipients {list of string} - the envelope recipient addresses
• message {string} - the full RFC 5322 message body

Throws

• {Error} - kind "smtp" when the session is closed, the server rejects a command, or an address is not ASCII-safe

#Structs

#smtp.Options

Connection settings for an SMTP session.

#smtp.Session

A live, authenticated SMTP connection: the handshake (greeting, EHLO, STARTTLS, and AUTH) has run once, so sendOn can deliver many messages over it. Value-semantic, but the conn handle is shared across copies (a net.Conn), so the socket survives being passed to sendOn. Build with open; retire with close.