mail

type AddressValue ¶

type AddressValue struct {
	// Name is the optional display name. It may hold any printable text,
	// including non-ASCII, which is RFC 2047 encoded at composition. CR, LF and
	// NUL are refused.
	Name string
	// Addr is the addr-spec: "local@domain", ASCII, in the dot-atom form of
	// RFC 5322 §3.4.1. Angle brackets are added by the composer and must not
	// appear here.
	Addr string
}

AddressValue is one RFC 5322 mailbox: an addr-spec and an optional display name.

It is deliberately NOT net/mail.Address, and the reason is measurable rather than aesthetic. net/mail.Address.String() emits its Address field verbatim:

mail.Address{Name: "ok", Address: "u@exa\r\nmple.com"}.String()
  == "\"ok\" <u@exa\r\nmple.com>"

The CRLF survives into the header, which is the injection this whole domain exists to refuse. The display name is protected there (it is RFC 2047 encoded, so a CRLF becomes "=0D=0A") and the address is not — so a caller who reached for the obvious stdlib helper would be protected on the field an attacker rarely controls and exposed on the one they usually do.

func (a AddressValue) IsZero() bool

type AttachmentValue ¶

type AttachmentValue struct {
	// Filename is the name presented to the recipient. It is required: an
	// attachment with no name is a part a client shows as "noname", and the
	// SDK will not invent one.
	Filename string
	// ContentType is the media type. Empty selects the type implied by the
	// filename's extension, and [DefaultAttachmentType] when there is none.
	ContentType string
	// ContentID, when non-empty, makes this part INLINE and referenceable as
	// cid:<ContentID>. It is an addr-spec-shaped token (RFC 2045 §7), written
	// without angle brackets — the composer adds them.
	ContentID string
	// Content is the part's bytes, base64 encoded at composition (RFC 2045
	// §6.8). An empty slice is a legal zero-length attachment.
	Content []byte
}

AttachmentValue is one MIME body part carrying a file.

The distinction between an attachment and an inline image is ONE field. A non-empty ContentID makes the part inline: it is placed in a multipart/related alongside the body (RFC 2387) and referenced from the HTML as cid:<ContentID> (RFC 2392 §2). An empty one makes it a regular attachment in a multipart/mixed (RFC 2046 §5.1.3).

That is why there is no Disposition field to set wrongly. The disposition and the enclosing multipart subtype are two halves of one decision, and letting a caller spell them separately is letting them disagree — which is exactly the message that renders as a broken image in one client and a stray attachment in another.

func (a *AttachmentValue) Inline() bool

type BatchSender ¶

type BatchSender interface {
	// SendBatch sends every message in msgs and returns the joined failures.
	// A nil error means every message was accepted.
	SendBatch(ctx context.Context, msgs []MessageValue) error
}

BatchSender sends several messages over ONE session. It is the ADR 0039 sibling of Transport, reached by type assertion:

if batch, ok := transport.(mail.BatchSender); ok {
	err = batch.SendBatch(ctx, notifications)
}

It is a capability and not a method, because it is not one for every transport: an HTTP provider API has no session to reuse, and a transport that implemented it by looping would be advertising an optimisation it does not perform.

The semantics of a partial failure are the reason this is not just a loop in the caller: SendBatch sends every message it can and returns the failures AGGREGATED with errors.Join, rather than stopping at the first. One bad recipient in a batch of five hundred must not silence the other four hundred and ninety-nine, and the caller still learns about it — errs.HasCode walks Unwrap() []error, so a joined error answers the same questions a single one does.

type DeliveryValue ¶

type DeliveryValue struct {
	// Envelope is the MAIL FROM and the RCPT TO list the session would issue.
	Envelope EnvelopeValue
	// Raw is the RFC 5322 message: headers, blank line, MIME body, CRLF line
	// endings throughout.
	Raw []byte
}

DeliveryValue is one record of what a transport actually put on the wire.

It carries the composed BYTES and not the message, because those are two different assertions. A test that checks the message checks what it itself built a moment earlier; a test that checks Raw checks what the composer produced — the encoded subject, the multipart structure, the absence of a Bcc header — which is the only half that can be wrong.

type EnvelopeValue ¶

type EnvelopeValue struct {
	// From is the return path (RFC 5321 §4.1.1.2): where a bounce goes. It is
	// the message's From addr-spec.
	From string
	// To is every RCPT TO the session will issue, in To, Cc, Bcc order. Bcc
	// recipients appear HERE and in no header.
	To []string
}

EnvelopeValue is what an SMTP session actually carries: one MAIL FROM and one or more RCPT TO (RFC 5321 §3.3). It is NOT the header block, and the difference is the whole reason this type exists.

A receiving MTA routes on the envelope and never on the headers. To, Cc and Bcc are text a client renders; the envelope is the delivery instruction. They agree by convention and not by protocol, which is how a Bcc can exist at all — and how a forwarding rule can deliver a message to somebody who appears in no header.

type FullTransport ¶

type FullTransport interface {
	Transport
	BatchSender
	Outbox
}

FullTransport is the union the SDK's in-memory transport returns: a Transport that also batches and records.

It exists for the same reason core/vfs.FullFS and core/metrics.FullMeter do — the port stays frozen and the capabilities stay assertable for a THIRD-PARTY transport that has neither, while a caller wiring one of the SDK's own does not have to type-assert for a feature it just constructed. A parameter should still ask for the narrowest thing it uses.

type HeaderFieldValue ¶

type HeaderFieldValue struct {
	// Name is the field name — printable US-ASCII without a colon
	// (RFC 5322 §3.6.8).
	Name string
	// Value is the unstructured field value. It is encoded per RFC 2047 when it
	// carries non-ASCII, folded to the RFC 5322 §2.1.1 line limits, and refused
	// outright when it carries CR, LF or NUL.
	Value string
}

HeaderFieldValue is one additional header: a name and a value.

It is a slice element rather than a map entry for two reasons that both matter: a map iterates in a random order, so the same message would compose to different bytes on different runs and no golden test could exist; and some fields legitimately repeat (Received, References), which a map cannot express at all.

type MessageValue ¶

type MessageValue struct {
	// Date is the origination date (RFC 5322 §3.6.1), which is REQUIRED in a
	// message. A zero Date is stamped by the composer from its clock rather
	// than refused: unlike a file mode, there is exactly one defensible value
	// and it is "now" (ADR 0031's clamping half).
	Date time.Time
	// From is the author mailbox (RFC 5322 §3.6.2). Exactly one is supported;
	// the multi-author form requires a Sender header to disambiguate and no
	// caller has ever wanted it by accident.
	From AddressValue
	// Subject is the unstructured subject field (RFC 5322 §3.6.5). Non-ASCII
	// content is encoded per RFC 2047 at composition; a CR or LF here is
	// [HeaderInjection].
	Subject string
	// MessageID is the optional Message-ID (RFC 5322 §3.6.4), angle brackets
	// included or omitted at the caller's choice — the composer adds them.
	//
	// An empty MessageID emits NO header. RFC 6409 §8.2 makes adding one the
	// submission server's job when it is absent, and generating one here would
	// mean inventing both entropy and a domain the SDK does not own.
	MessageID string
	// ReplyTo is the optional Reply-To mailbox list (RFC 5322 §3.6.2).
	ReplyTo []AddressValue
	// To is the primary recipient list (RFC 5322 §3.6.3).
	To []AddressValue
	// Cc is the carbon-copy recipient list (RFC 5322 §3.6.3).
	Cc []AddressValue
	// Bcc is the blind carbon-copy list. It reaches the ENVELOPE and never a
	// header — see [MessageValue.Envelope].
	Bcc []AddressValue
	// Headers are additional fields, emitted in slice order so a composed
	// message is byte-deterministic. A name the composer owns is
	// [ReservedHeader]; see [IsReservedHeader].
	Headers []HeaderFieldValue
	// Text is the text/plain body.
	Text string
	// HTML is the text/html body. With Text it becomes a multipart/alternative
	// in which the plain part comes FIRST — RFC 2046 §5.1.4 orders alternatives
	// by increasing preference, so the last one is the one a client shows.
	HTML string
	// Attachments are the file parts. One carrying a ContentID is INLINE and is
	// referenced from the HTML body as cid:<ContentID> (RFC 2392 §2).
	Attachments []AttachmentValue
}

MessageValue is one mail, as a value. It is deliberately a struct and not an interface: a message has no behaviour worth abstracting, it is data, and a value can be built in a literal, compared field by field in a test, and carried across a goroutine without a lock.

Nothing here is a wire format. The MIME structure the fields imply is chosen by the composer in internal/service/mail, and which parts appear is a pure function of which fields are populated — see that package's CLAUDE.md for the table.

Every string field that reaches a header is validated by Validate. The slices are never mutated by this package.

func (m MessageValue) Envelope() (envelope EnvelopeValue, err error)

type Outbox ¶

type Outbox interface {
	// Sent returns the deliveries recorded so far, oldest first. The returned
	// slice and every byte slice in it are the caller's own copy.
	Sent() []DeliveryValue
	// Reset discards the record, so one test's messages are not another's.
	Reset()
}

Outbox exposes what a transport has been asked to send. It is the ADR 0039 sibling that makes a test double a double rather than a stub:

if box, ok := transport.(mail.Outbox); ok {
	sent := box.Sent()
}

Only an in-memory transport implements it, and that is the point — a consumer's test asserts against this interface without importing the SDK's service layer, and a production transport that started implementing it would be a transport keeping every message it ever sent in memory.

type Transport ¶

type Transport interface {
	// Send composes msg and hands it to the next hop.
	//
	// It validates before it dials: a message that cannot be composed is
	// refused without opening a socket, so a header-injection attempt never
	// reaches a server and never costs a connection.
	//
	// ctx bounds the whole attempt. A transport that cannot honour a deadline
	// natively must still stop when ctx does — by severing its own connection
	// if that is the only mechanism available — because a Send that outlives
	// its context is a goroutine the caller believes it has cancelled.
	Send(ctx context.Context, msg MessageValue) error
}

Transport carries a message to whatever will deliver it. It is FROZEN at one method.

One method, because "send this mail" is the only thing every transport can do. A capability that some transports have arrives as a SIBLING interface reached by type assertion, never as a second method (ADR 0039): pkg/v1/mail aliases this type, Go interfaces are structural, and a second method would break every downstream implementation at compile time with no deprecation window.

Implementations MUST be safe for concurrent use.

What a Transport does NOT promise is as important as what it does. A nil error means the message was ACCEPTED by the next hop — nothing more. It is not a promise of delivery, of inbox placement, or of the recipient existing: SMTP accepts responsibility hop by hop (RFC 5321 §6.1), and the hop that eventually refuses reports it in a bounce message hours later, to the envelope's return path, over a channel this port has no access to.

It is named for the ROLE it plays rather than for its one method: "the SMTP transport" and "the in-memory transport" are the words this domain is discussed in, and a Sender would name the verb instead.

IFACE-PLUGIN: the concrete transports stay unexported behind their constructors in internal/service/mail.