Send transactional email via API

StretchSMTP sends transactional email for your applications — password resets, receipts, alerts, magic links — from your own domain, signed with your own DKIM key, straight to the recipient's inbox. It is an API, not an inbox: you POST a message and read back delivery logs.

You will register a sending domain, publish DNS records, verify, get an API key, and then send your first email.

Note: StretchSMTP calls run against the StretchSuite API base /api/v1/stretchsmtp. The service must be enabled for your organization; if calls return STRETCHSMTP_DISABLED, ask your administrator to enable it.

Step 1 — Register a sending domain

Register the domain you will send from (for example yourdomain.com, so you can send as no-reply@yourdomain.com).

In the StretchSMTP dashboard, open Sending domains → Add domain, or call the API:

POST /api/v1/stretchsmtp/domains
{
  "domain": "yourdomain.com",
  "selector": "stretchsmtp",
  "dmarc_policy": "none",
  "mail_from_domain": "yourdomain.com"
}

selector defaults to stretchsmtp and dmarc_policy defaults to none — both are optional. StretchSMTP generates a fresh RSA-2048 DKIM keypair for your domain (the private key never leaves the server) and returns a dns_records array — the exact records to publish.

Step 2 — Publish the DNS records

Add these three TXT records at your DNS provider. Copy the DKIM value from the dashboard/API response — it is unique to your domain.

Notes:

• DKIM host uses your selector — with the default selector it is stretchsmtp._domainkey.yourdomain.com. The p= value is your public key.
• SPF authorizes StretchSMTP's sending hosts. If the dashboard shows sending IPs, they appear as ip4: / ip6: mechanisms; the record always ends in ~all.
• DMARC starts at p=none (monitor only) with relaxed alignment (adkim=r; aspf=r). Tighten to quarantine or reject after you have confirmed clean authentication. The rua= address is your mail_from_domain.

Tip: If your DNS provider appends the domain automatically, enter just the host portion (stretchsmtp._domainkey, @, _dmarc) rather than the full name.

Step 3 — Verify the domain

In the dashboard click Verify, or call:

POST /api/v1/stretchsmtp/domains/yourdomain.com/verify

The response reports each check and an overall status:

{ "domain": "yourdomain.com", "dkim": true, "spf": true, "dmarc": true, "status": "verified" }

The domain becomes verified once the DKIM record resolves and matches your key. SPF and DMARC are reported alongside so you can confirm all three pass. DNS can take a few minutes to propagate — re-run verify if it is not ready yet.

Step 4 — Get your API key

StretchSMTP calls are authenticated as your organization through the protected StretchSuite API. Get your API credential from the dashboard under API keys / Settings (or from your administrator). Send it on every request as your workspace's API key — the same credential that scopes the call to your organization. Keep it secret and server-side; never ship it in client-side code.

Step 5 — Send your first email

Once the domain is verified, POST a message. The from address must be on a domain you registered.

POST /api/v1/stretchsmtp/send
{
  "from": { "email": "no-reply@yourdomain.com", "name": "Your App" },
  "to": "customer@example.com",
  "subject": "Welcome to Your App",
  "text": "Thanks for signing up!",
  "html": "<p>Thanks for signing up!</p>",
  "reply_to": "support@yourdomain.com"
}

Payload rules, straight from the API:

• from — required. Either a string ("no-reply@yourdomain.com") or an object { "email": ..., "name": ... }. Its domain must be registered, or the call returns DOMAIN_NOT_REGISTERED.
• to — required. A single address or an array. cc and bcc are optional and accept the same shape.
• subject — the subject line.
• text and/or html — at least one body is required, or the call returns NO_BODY. Send both for best rendering.
• reply_to — optional reply address.
• headers — optional object of extra headers. metadata — optional object stored with the message for your own reference.

A successful call queues one message per unique recipient and returns:

{ "group_id": "…", "queued": 1, "suppressed": [], "recipients": [ { "id": "…", "to_email": "customer@example.com", "status": "queued" } ] }

Any recipient already on your suppression list is skipped and listed under suppressed instead of queued. Each queued message is DKIM-signed and delivered by the worker.

Step 6 — Check delivery status

• List messages / logs: GET /api/v1/stretchsmtp/messages returns your recent messages with their current status (queued, sending, sent, deferred, failed).
• Service status: GET /api/v1/stretchsmtp/status shows whether sending is in direct or relay mode and the configured sending IPs — useful when composing SPF.

A message moves queued → sending → sent on success. Temporary failures go to deferred and retry on a backoff (roughly 1, 5, 15, 60, 180, 360, then 720 minutes) until it delivers or exhausts its attempts and becomes failed.

Handle bounces and the suppression list

StretchSMTP keeps a per-organization suppression list so you stop mailing addresses that hard-bounce or complain — protecting your sending reputation.

• View it: GET /api/v1/stretchsmtp/suppressions
• Add an address: POST /api/v1/stretchsmtp/suppressions with { "email": "bad@example.com", "reason": "manual" }
• Remove an address: DELETE /api/v1/stretchsmtp/suppressions/bad@example.com

Suppressed recipients are automatically skipped on every send (they come back in the suppressed array), so you never have to filter them yourself. When a message hard-bounces, add the address to suppression; if a bounce was a one-off (a full mailbox, a typo the user fixed), remove it to resume sending.

Tip: Treat a soft/temporary failure (deferred) differently from a hard bounce. Deferrals retry on their own — do not suppress them. Suppress only confirmed hard bounces and complaints.

Troubleshooting

• STRETCHSMTP_DISABLED (503). The service is off for your organization; ask your administrator to enable it.
• DOMAIN_NOT_REGISTERED. The from domain has no registered sending domain. Register and verify it first (Steps 1–3).
• NO_BODY / NO_RECIPIENTS / INVALID_FROM. Include at least one of text/html, at least one valid recipient, and a valid from address.
• Verify says DKIM false. The DKIM TXT record has not propagated or does not match. Confirm the host is stretchsmtp._domainkey.yourdomain.com and the p= value matches the dashboard, then re-verify.
• Mail sends but lands in spam. Make sure SPF and DKIM both pass, keep early volume low to warm the domain, and only raise DMARC to quarantine/reject after authentication is clean.

What's different: StretchSMTP vs StretchMail

• StretchSMTP is a transactional email API — your application sends mail programmatically and reads delivery logs. No inbox. Use it for receipts, resets, and notifications at scale.
• StretchMail is an email client — a Gmail-class inbox for people to read, reply, thread, and label mail at you@yourdomain.com. Use it for human correspondence.

Under the hood, StretchSMTP is the engine that actually sends; StretchMail (and other StretchSuite apps) rely on it to deliver. To set up a human inbox instead, see Set up email on your own domain under StretchMail.