SMTP settings

If your framework, CMS or device already speaks SMTP, you can send through api.email without changing code. SMTP messages use the same API key, appear in the same logs and trigger the same webhooks as API requests.

Connection settings

Unencrypted connections are refused. The From address must be on a verified domain, exactly as with the API.

Nodemailer

import nodemailer from 'nodemailer';

const transport = nodemailer.createTransport({
  host: 'smtp.api.email',
  port: 587,
  secure: false, // upgraded with STARTTLS
  auth: { user: 'api', pass: process.env.API_EMAIL_KEY },
});

await transport.sendMail({ from: 'Acme <[email protected]>', to: '[email protected]', subject: 'Hi', text: 'Hello' });

Django

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.api.email"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "api"
EMAIL_HOST_PASSWORD = os.environ["API_EMAIL_KEY"]

Laravel

MAIL_MAILER=smtp
MAIL_HOST=smtp.api.email
MAIL_PORT=587
MAIL_USERNAME=api
MAIL_PASSWORD="${API_EMAIL_KEY}"
MAIL_ENCRYPTION=tls

API or SMTP?

Both deliver the same email. The API is the better default for new code: one HTTPS request instead of several protocol round trips, an email id in the response that you can track, idempotency keys that make retries safe, and JSON errors instead of SMTP reply codes. Choose SMTP when you cannot change the sending code, for example in a CMS, a hosted app or a printer that emails scans.

Tags and idempotency over SMTP

SMTP has no fields for these, so use headers: X-API-Email-Tags: receipt,billing adds tags, and Idempotency-Key: receipt-1042 works the same way as on the API. Most SMTP libraries let you add custom headers to a message.

Limits

SMTP sends count against the same monthly quota as API requests and share the same rate limits. Keep connections open and reuse them for several messages instead of opening a new connection per email; most libraries pool connections when you create the transport once at startup.