mailer

type Address struct {
	// Name is the display name; it may be empty.
	Name string `json:"name,omitempty"`
	// Address is the email address, "ada@example.com".
	Address string `json:"address"`
}

type Attachment struct {
	// Filename is the file's name, as the recipient sees it.
	Filename string `json:"filename"`
	// ContentType is the file's media type. Default: from the
	// filename's extension, or application/octet-stream.
	ContentType string `json:"content_type,omitempty"`
	// Data is the file's content.
	Data []byte `json:"data"`
	// ContentID makes the file inline, shown in the HTML body by
	// <img src="cid:ContentID">, rather than attached.
	ContentID string `json:"content_id,omitempty"`
}

type Config struct {
	// Driver is how emails are sent: log (written to the app's log),
	// smtp, memory (kept, for tests), or one passed to ForApp
	// (postmark). MAIL_DRIVER, default log.
	Driver string `env:"MAIL_DRIVER" default:"log"`
	// FromAddress is the sender of messages without one.
	// MAIL_FROM_ADDRESS.
	FromAddress string `env:"MAIL_FROM_ADDRESS"`
	// FromName is the sender's name. MAIL_FROM_NAME, default APP_NAME.
	FromName string `env:"MAIL_FROM_NAME"`
	// SMTPURL is the SMTP server: smtp://user:password@host:587 (with
	// STARTTLS) or smtps://…:465 (TLS); a Secret, since it holds the
	// password. MAIL_SMTP_URL, default smtp://127.0.0.1:1025 (Mailpit,
	// for development).
	SMTPURL anetos.Secret `env:"MAIL_SMTP_URL" default:"smtp://127.0.0.1:1025"`
}

type Driver struct {
	// Name is the value of MAIL_DRIVER that selects the driver.
	Name string
	// Open returns the transport for the app. If it implements
	// io.Closer, it is closed when the app shuts down.
	Open func(app *anetos.App, cfg Config) (Transport, error)
}

type LogTransport struct {
	// contains filtered or unexported fields
}

type Mailable interface {
	// Build returns the message to send; ctx is Send's (or Queue's).
	Build(ctx context.Context) (*Message, error)
}

type Mailer struct {
	// contains filtered or unexported fields
}

type MemoryTransport struct {
	// contains filtered or unexported fields
}

type Message struct {
	// From is the sender. Default: MAIL_FROM_ADDRESS and MAIL_FROM_NAME.
	From Address
	// To, Cc and Bcc are the recipients: at least one in all. Bcc
	// recipients get the email without being listed in it.
	To, Cc, Bcc []Address
	// ReplyTo is where replies go, if not to From.
	ReplyTo []Address
	// Subject is the subject line.
	Subject string
	// HTML is the HTML body: a templ component (or any view.Component),
	// rendered with the context of Send. Use inline styles: many mail
	// clients ignore style sheets.
	HTML view.Component
	// Text is the plain-text body, as is (build it with fmt or
	// text/template: templ would HTML-escape it). Without it, the HTML
	// body's text is used: paragraphs, lists, and links followed by their
	// URL. At least one of HTML and Text is required.
	Text string
	// Attachments are files sent with the email.
	Attachments []Attachment
	// Headers are extra headers, such as List-Unsubscribe. They can't
	// replace the ones the message sets (From, To, Subject, Date, …).
	Headers map[string]string
	// Tag labels the email for API drivers that group emails by it
	// (Postmark); SMTP ignores it.
	Tag string
	// Metadata labels the email with pairs that API drivers keep with it
	// (Postmark); SMTP sends them as X-Metadata-<key> headers. Keys are
	// letters, digits, - and _.
	Metadata map[string]string
}

type Option func(*Mailer)

type Outgoing struct {
	// MessageID is the Message-ID header's value, without the angle
	// brackets: unique, and kept if the email is sent again.
	MessageID string `json:"message_id"`
	// Date is when the email is sent: when it was rendered, or, for
	// queued mail, when the job sends it.
	Date time.Time `json:"date"`
	// From is the sender: the message's, or the mailer's default.
	From Address `json:"from"`
	// To is the main recipients.
	To []Address `json:"to,omitempty"`
	// Cc is the copied recipients.
	Cc []Address `json:"cc,omitempty"`
	// Bcc is the hidden recipients: in the SMTP envelope, not the
	// message.
	Bcc []Address `json:"bcc,omitempty"`
	// ReplyTo is where replies go.
	ReplyTo []Address `json:"reply_to,omitempty"`
	// Subject is the subject line.
	Subject string `json:"subject"`
	// HTML is the HTML body; it may be empty.
	HTML string `json:"html,omitempty"`
	// Text is the plain-text body.
	Text string `json:"text"`
	// Attachments are as in [Message], with their content types set.
	Attachments []Attachment `json:"attachments,omitempty"`
	// Headers are the message's extra headers.
	Headers map[string]string `json:"headers,omitempty"`
	// Tag is the message's tag.
	Tag string `json:"tag,omitempty"`
	// Metadata is the message's metadata.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type Record struct {
	// Mailable is the mailable given to Send or Queue.
	Mailable Mailable
	// Message is the email it rendered.
	Message *Outgoing
	// Queued says it went through Queue: a job sends it.
	Queued bool
}

type SMTPTransport struct {
	// contains filtered or unexported fields
}

type Transport interface {
	// Send sends m, which [Outgoing.Validate] accepted. An error that
	// retrying won't fix (a rejected address, a refused message) should
	// be queue.Permanent, so a queued email fails at once.
	Send(ctx context.Context, m *Outgoing) error
}