On this page
Configure outgoing email
Choose SMTP or Graph, protect runtime credentials and preserve provider outcomes.
Choose SMTP or Microsoft Graph, protect runtime secrets and preserve the difference between provider acceptance and delivery. Foundation 0.19.0 supplies sending adapters; campaigns, mailing lists, outboxes, pacing and recipient consent belong to the application.
Select the connection model
| Situation | Path | What you supply |
|---|---|---|
| One deployment-owned SMTP sender | AddFabricatorsMail and IMailTransport |
Trusted host SMTP settings and authorized system-mail use |
| Customers configure their own SMTP | AddFabricatorsConnectedSmtp and IConnectedMailTransport |
Current connection authority and runtime settings source |
| Microsoft 365 mailbox or shared mailbox | AddFabricatorsGraphMail and IConnectedMailTransport |
Exact selected mailbox, approved OAuth grant and token source |
| HTML/text from reviewed data | Optional Scriban adapter | Reviewed template, JSON data and rendering budget |
A relay is not a requirement for Microsoft 365: use Graph with the mailbox's approved application/delegated permissions. A user login through Microsoft OIDC does not automatically grant access to their mail. Gmail/Workspace sending via SMTP OAuth needs the product's corresponding Google grant/token implementation; a native Gmail API transport is not supplied by this release.
Store configuration, not live clients
For runtime connections, persist the protocol, mailbox, allowed sender aliases, ownership, enabled state and revision. Protect passwords/refresh tokens using secret protection and an EF key ring. Keep keys readable across replicas and restarts, with the chosen application discriminator and key encryption policy.
Do not serialize an authenticated MailKit client or keep a mutable tenant SMTP
profile in a singleton. ISmtpConnectionSettingsSource returns the trusted
snapshot for the selected connection; it can change without restarting the host.
Use the runtime SMTP verification service to check a saved
or proposed profile before application use. Verification is not an email delivery
receipt or permission to expose the password in a response.
Register authority and sending
Register only the adapters needed by the host. The product supplies
IMailConnectionAuthority: resolve the connection under the current caller, then
revalidate its complete snapshot, revision and current grants immediately before
network submission. An opaque connection ID is a selector, not authorization.
OAuth connections also need IMailAccessTokenSource. The token lease must match
the connection/revision/audience and remain valid for the submission window.
Protect persisted refresh tokens, serialize refresh across replicas and handle
revoked grants explicitly. Foundation does not supply a consent UI, MSAL refresh
store or silent fallback from OAuth to a password. These boundaries avoid hiding
token-loss bugs inside the sender.
Read the exact connection and token contract before implementing these ports. Scoped authorities must remain scoped in workers as well as HTTP hosts.
Choose TLS and size policy deliberately
Required STARTTLS is the normal SMTP default. If an internal certificate fails only revocation lookup, the explicit revocation-only policy is narrower than accepting every certificate. Insecure certificate acceptance and cleartext relay transport are different opt-ins; neither triggers an opportunistic downgrade. See certificate policy and compatibility options.
Rendering budgets count source/model/output characters and execution work. MIME limits count the final message, including headers, encoding and multipart bytes. The provider can impose a lower limit: SMTP's advertised SIZE and Graph's encoded request ceiling are checked separately. Raising a render limit does not raise a provider quota. Oversize messages are rejected, not split or truncated automatically. Use the size-policy reference when selecting host and per-connection limits.
Submit from a durable product workflow
Persist the business change and outbox intent atomically. A worker then leases the item, resolves current authority, renders if needed and submits outside that database transaction. Persist the outcome before advancing the queue.
SMTP acceptance or Graph HTTP 202 means accepted for processing, not delivered to
an inbox. A disconnect after submission may be UnknownOutcome; preserve that
uncertainty instead of blindly resending. Follow Retry-After and your own
reconciliation/idempotency policy. A stable MessageId supports correlation but is
not a provider-guaranteed deduplication key.
Incoming mail is a separate boundary: reader/folder/cursor contracts exist, while Graph/IMAP polling, attachments and webhook synchronization are not implemented. Do not configure a mailbox as "connected for reading" based only on successful send.
Next: full mail contract, background execution, MailKit API or Graph API.