SMTP

SMTP is the standard protocol for handing mail to a mail server. It is named as an email driver in the MainSDK requirements, so your app could send through any SMTP server: your company's relay, a self-hosted server, or a provider that offers SMTP access. Pick it when no API driver fits, or when policy requires mail to leave through your own relay.

email:
  driver: smtp

Before you start

1. Get the server's host, port and credentials for this app.
2. Use a server that supports TLS, and make sure your sending domain has SPF and DKIM set up for it.

Store the password in your secrets manager.

Configure

email:
  driver: smtp                 # planned driver, not in the spec yet
  key: secret:SMTP_PASSWORD    # suggested name; [to be decided] host, port and username keys are not in the spec

A literal password fails to load with MAIN-CONFIG-0004.

Use it

import { email } from "mainsdk";

await email.send({ to: user.email, template: "welcome", data: {} });

Local development and testing

mainsdk dev sends every email to the local inbox, so you don't need a mail server. createTestApp() from @mainsdk/testing runs email on its in-memory fake, and chaos.on("email", { outage: true }) simulates an outage.

What MainSDK adds on top

• Marketing email does not compile without an unsubscribe, with one-click unsubscribe headers.
• Unsubscribes, bounces and complaints suppressed for every later send.
• No tracking pixels or rewritten links by default; a retry never sends twice.

See Email.

Limits and notes

• Planned driver, not in the spec yet; it comes through the driver kit later.
• SMTP has no standard way to report bounces and complaints back; how this driver feeds the suppression list is not decided yet.
• Your server's host must be in the app's allowed network destinations.

Swap to or from it

email:
  driver: resend   # was smtp

Email is stateless, so the swap needs no migration.

FAQ

Can I use SMTP today? Not through MainSDK yet. Use Resend or Amazon SES.

Next

• Email
• Resend, Amazon SES and Postmark

Open questions