Send transactional email with Amazon SES

Amazon SES is a solid default when you want predictable cost at scale and you already run infrastructure in AWS. LetterStack sits on top: your SES SMTP credentials, plus templates, a REST send endpoint, and delivery logs-without paying a managed provider per thousand emails on top of SES itself.

This guide walks through SES setup, LetterStack configuration, and a real POST /v1/emails/send call. For local testing before SES is ready, see Connect Gmail SMTP to LetterStack.

When SES makes sense

You send enough volume that SES pricing beats hobby Gmail limits.
You want DKIM/SPF on your own domain and full control of reputation.
You already have an AWS account and are fine managing sandbox exit and bounces.

LetterStack does not replace SES-it connects to SES over SMTP the same way your app would, then adds the developer layer (Handlebars, API keys, logs).

1. Prepare Amazon SES

Work in the AWS SES console in the region you will send from (for example us-east-1).

Verify a domain (recommended) or a single email address under Verified identities.
Add the DKIM DNS records SES provides so mail clients trust your domain.
If the account is new, you start in the sandbox: you can only send to verified addresses until you request production access.

For production apps, plan to exit sandbox before launch week traffic.

2. Create SMTP credentials in SES

In SES, open SMTP settings for your region.
Create an SMTP user (IAM-backed). Download or copy the username and password-this is not your AWS console password.
Note the SMTP endpoint host, for example:

email-smtp.us-east-1.amazonaws.com

Use port 587 with STARTTLS (LetterStack’s default encryption mode) or 465 with implicit TLS.

3. Add SES SMTP in LetterStack

Sign in to the LetterStack dashboard.
Open Projects → your project → SMTP in the sidebar.
Click Add SMTP and create a config with slug ses-production:
- Host: email-smtp.us-east-1.amazonaws.com (match your region)
- Port: 587
- Encryption: STARTTLS
- Username / password: SES SMTP credentials
- From email / name: an address on your verified domain (for example [email protected])

Click Create config. LetterStack tests the connection on save-fix credentials, port/encryption, or SES identity/sandbox limits if the test fails.

Your first SMTP config is the default automatically. To switch later, use the star icon on another config in the list.

4. Create an API key and a template

Under API keys, generate a key (ls_live_…). Copy it once; it is not shown again.
Under Templates, create a simple transactional template, for example slug password-reset:

Subject: Reset your password, {{name}}

HTML body (minimal):

<p>Hi {{name}},</p>
<p><a href="{{reset_url}}">Reset your password</a></p>
<p>If you did not request this, ignore this email.</p>

Keep the template active.

5. Send with curl

Replace the API key, recipient, and variables with your values:

curl -X POST https://api.letterstack.dev/v1/emails/send \
  -H "Authorization: Bearer ls_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "password-reset",
    "to": "[email protected]",
    "variables": {
      "name": "Alex",
      "reset_url": "https://myapp.com/reset?token=example"
    }
  }'

A successful call returns 202 Accepted with "status": "queued". LetterStack renders Handlebars, queues delivery, and sends through your SES SMTP with retries.

6. Verify in email logs

Open Email logs (sidebar Logs) for the project. You should see the recipient, template slug, subject, and status sent or failed (with SMTP error detail when failed).

Common API errors on first send:

Error	Meaning
`smtp_not_configured`	No default SMTP config on the project
`from_email_required`	Template send needs a from address-set default on SMTP config
`not_found`	Template slug typo or template inactive
`template_render_error`	Handlebars variable missing in HTML or subject

7. Production checklist

Exit SES sandbox and monitor bounces/complaints in AWS.
Align SPF, DKIM, and DMARC for your sending domain.
Store API keys server-side only; never embed ls_live_ keys in frontend bundles.
Rate limit: 100 sends/minute per API key-see the API reference.

Local dev without SES

Use Gmail SMTP for quick tests: Connect Gmail SMTP to LetterStack. Switch the project default to SES when you deploy.

Create an account and connect SES in the dashboard. API reference: docs.