Documentation
¶
Overview ¶
Package email sends transactional mail, over one of six vendors or nowhere at all.
The interface is Emailer, and it is deliberately one method: send this OutboundEmailMessage, or say why not. Templating, retries beyond the vendor's own, batching, and scheduling are not here — an application that wants them composes them around this, and an application that does not is spared them.
The providers ¶
Each is a subpackage translating an OutboundEmailMessage onto one vendor's API, and each constructor returns its own concrete type rather than the interface:
mailgun Mailgun's messages API mailjet Mailjet's v3.1 send API postmark Postmark's email API resend Resend's emails API sendgrid SendGrid's v3 mail send ses Amazon SES noop accepts every message and delivers none
Six vendors and a noop, because near-identical translations to seven different APIs are seven files a reader opens for the lines that differ. They are left that way deliberately; see llm/doc.go for the long form of that decision.
github.com/primandproper/primitives-go/v2/email/config is what selects one from configuration and wraps it in a circuit breaker. Its provider roster is the ground truth for the list above, which is checked against it rather than maintained beside it.
noop is not a fallback. An unset or misspelled provider is github.com/primandproper/primitives-go/v2/errors.ErrUnknownProvider, because outbound mail that silently goes nowhere is discovered by the people who never received it. Discarding mail has to be asked for by name.
Addresses ¶
FormatAddress is the one place this module escapes a display name into an RFC 5322 mailbox, and every provider whose payload carries a mailbox header — mailgun, postmark, resend, ses — reaches it. A second copy of that escaping is a second chance to get a comma wrong, and nothing would say which copy did. SendGrid and Mailjet carry the name and the address as separate JSON fields and so escape nothing; each of their docs says why.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatAddress ¶
FormatAddress renders a display name and address as one RFC 5322 mailbox, quoting and escaping the name. An empty name yields the bare address.
It is a shared function rather than a Sprintf at each provider — as three of them used to have — because the escaping is load-bearing. A comma in an attacker-influenced display name injects extra recipients wherever the provider accepts a comma-separated list, which several of them do; net/mail's own rendering is what quotes it.
Four providers carried a byte-identical copy of this and only one carried the reason for it, which is the argument for one home: the copy most likely to be deleted by somebody tidying is one of the three that looks like a formatting convenience.
Types ¶
type Emailer ¶
type Emailer interface {
SendEmail(ctx context.Context, details *OutboundEmailMessage) error
}
Emailer represents a service that can send emails.
type OutboundEmailMessage ¶
type OutboundEmailMessage struct {
ToAddress string `json:"toAddress"`
ToName string `json:"toName"`
FromAddress string `json:"fromAddress"`
FromName string `json:"fromName"`
Subject string `json:"subject"`
HTMLContent string `json:"htmlContent"`
}
OutboundEmailMessage is a collection of fields that are useful for sending emails.
It carries only what an SMTP-or-API emailer needs to address and render one message. Application identifiers — which user this concerns, which test produced it — belong to the application's own envelope, not to the platform's transport type.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package emailcfg selects and builds an email.Emailer from configuration over six vendors — SendGrid, Mailgun, Mailjet, Resend, Postmark, SES — or the noop emailer.
|
Package emailcfg selects and builds an email.Emailer from configuration over six vendors — SendGrid, Mailgun, Mailjet, Resend, Postmark, SES — or the noop emailer. |
|
Package mailgun sends email through Mailgun.
|
Package mailgun sends email through Mailgun. |
|
Package mailjet sends email through Mailjet.
|
Package mailjet sends email through Mailjet. |
|
Package emailmock provides moq-generated mock implementations of the email package's interfaces.
|
Package emailmock provides moq-generated mock implementations of the email package's interfaces. |
|
Package noop is the email.Emailer that sends nothing.
|
Package noop is the email.Emailer that sends nothing. |
|
Package postmark sends email through Postmark.
|
Package postmark sends email through Postmark. |
|
Package resend sends email through Resend.
|
Package resend sends email through Resend. |
|
Package sendgrid sends email through SendGrid.
|
Package sendgrid sends email through SendGrid. |
|
Package ses sends email through Amazon SES v2.
|
Package ses sends email through Amazon SES v2. |