Why double opt-in
A form that accepts any address will eventually collect addresses that aren't the visitor's: typos, pranks, bots. Emailing those hurts the people on the receiving end and your sender reputation. Double opt-in fixes it: an address only joins the list after its owner clicks a link sent to that address. It also gives you a clean record of consent.
The wiring
Step by step
1. React to the write, don't block it
The table now has a stream (NEW_IMAGE). A Lambda event source mapping reads it, with a filter so the function only wakes up for brand-new items. The function's own updates to the item would otherwise trigger it again, and filtering at the source means those never cost an invocation:
ConfirmStreamMapping:
Type: AWS::Lambda::EventSourceMapping
Properties:
EventSourceArn: !GetAtt SubscribersTable.StreamArn
FilterCriteria:
Filters:
- Pattern: '{"eventName": ["INSERT"]}'
MaximumRetryAttempts: 3
BisectBatchOnFunctionError: true
FunctionResponseTypes: [ReportBatchItemFailures]
DestinationConfig:
OnFailure:
Destination: !GetAtt ConfirmFailureQueue.Arn
Partial batch responses mean one bad record is retried on its own instead of dragging its batch-mates along, and anything that still fails lands in an SQS queue instead of disappearing.
2. Issue a token, idempotently
The function generates a random token (secrets.token_urlsafe(32)) and stores it with a conditional update: only if the item is still pending and doesn't have a token yet. Stream records can be delivered more than once, so the condition is what makes a retry safe. If the update fails because a token already exists and no email has gone out, the function reuses that token. One subscriber, one link, however many retries.
3. Send, then start the clock
The email goes out through SES from hello@serverlesssociety.com, DKIM-signed by the domain. Only after SES accepts it does the function set sentAt and expiresAt (7 days out). DynamoDB's TTL feature deletes unconfirmed items when expiresAt passes, for free.
The ordering matters. If expiresAt were set before sending, a sending outage would quietly delete sign-ups that never got their email. This way, an item that was never emailed is never expired. It waits, stored, until it can be sent.
4. Confirm with a click, not a fetch
Corporate mail filters open links in emails to scan them. If the link itself confirmed the subscription, the scanner would confirm it, and double opt-in would mean nothing. So the link opens a static page, /newsletter/confirm/, with a Yes, subscribe me button. The button posts the email and token to /api/confirm. The page also strips the token from the address bar as soon as it loads.
The confirm endpoint is part one's pattern again: API Gateway validates the body (the token must be exactly 43 URL-safe characters) and calls DynamoDB directly:
"UpdateExpression": "SET #s = :confirmed, confirmedAt = :now REMOVE confirmToken, expiresAt",
"ConditionExpression": "confirmToken = :t AND #s = :pending"
Removing expiresAt cancels the TTL deletion; removing the token makes the link single-use. A wrong, reused or expired token fails the condition and gets one generic 400. No Lambda, and no way to tell which of those it was.
Things we learned the hard way
- The SES sandbox fails as
AccessDenied, notMessageRejected. New SES accounts can only send to verified addresses. Because the function's IAM policy scopesses:SendEmailto our domain identity, sending to an unverified recipient in the sandbox comes back as an authorization error. Those records retry, land in the failure queue, and the sign-up stays stored as pending with no expiry, ready to be re-sent once production access is granted. - Test with the mailbox simulator.
success@simulator.amazonses.comaccepts mail even from a sandboxed account, so the whole flow (subscribe, token, send, confirm, single-use) can be tested end to end before anyone real signs up. - DKIM before anything. SES won't send from the domain until its three DKIM CNAMEs resolve. A
_dmarcTXT record withp=nonecosts nothing and helps receiving servers trust the mail.
Control plane vs data plane
| Plane | What | When |
|---|---|---|
| control | Stream, TTL, function, event source mapping, SES identity, confirm method, IAM roles | One reviewed CloudFormation change set |
| data | GetRecords, UpdateItem, ses:SendEmail, and on click UpdateItem again | Every sign-up and every confirmation |
What it costs
Per sign-up: a few stream reads (free for Lambda triggers), one short Lambda invocation (well inside the free tier at newsletter scale), one SES email at $0.10 per thousand, two small DynamoDB writes, and one API call on confirm. A thousand sign-ups costs on the order of ten cents, nearly all of it email. Check current SES and Lambda pricing for your region.
Well-Architected checklist
- Operational excellence: everything in the same template; logs kept 30 days; failures visible in one queue instead of scattered across log lines.
- Security: the function can read one stream, update one table, and send only as
hello@our domain; tokens are random, single-use and validated by shape at the gateway; confirmation needs a human click. - Reliability: the sign-up never depends on email; conditional writes make retries idempotent; partial batch failures, bisecting and an on-failure queue; nothing expires until it was actually emailed.
- Performance efficiency: events filtered at the source; arm64 function; the confirm path is a single gateway-to-table hop.
- Cost optimization: pay per sign-up; TTL deletes stale data for free; no idle compute.
- Sustainability: the function runs only for new sign-ups, a few hundred milliseconds each.
When not to do this
- You need the email inside the request. If the client must know the email was accepted by SES before you answer, you want a synchronous call, and you give up storage-first's guarantee.
- You already run an email platform. If your marketing tool handles opt-in, send it the event (EventBridge, a webhook) instead of rebuilding consent tracking.
- High volume. At serious scale, add an SES configuration set for bounce and complaint events, and keep a suppression list so you never email a bounced address twice.
Join the field notes → · Part one: storage-first APIs · All posts