Skip to content
fabricators docs
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.

↑ ↓ to move↵ to openSearching fabricators .NET foundation v0.19.0