Sending email from serverless functions: pitfalls and patterns

handler:
  sendEmail(...)        // not awaited
  return response

Pitfall 4: timeouts shorter than the send#

If your function limit is five seconds and the provider occasionally takes six, those messages fail even though they may eventually be sent.

Fix:

• Set an explicit client timeout shorter than the function limit, so you can fail cleanly and retry.
• Keep the function's own limit comfortable.
• Treat a timeout as unknown, not as failure: the message may have been sent. Use idempotency keys when you retry.

Pitfall 5: connection overhead and cold starts#

With SMTP, every invocation may need to connect, negotiate encryption and authenticate before sending. That adds latency, and connections cannot be reused across cold starts. See SMTP or API for sending email.

Fix:

• Prefer an HTTP API, which needs one request per message and works well with short-lived processes.
• Create the client outside the handler so warm invocations reuse it.
• If you must use SMTP, use a queue worker that runs longer and keeps connections open, not the request function.

Pitfall 6: bursts hit rate limits#

A marketing event or a bug can trigger thousands of functions at once, each trying to send. The provider answers with rate-limit errors, and your retries make it worse.

Fix:

• Limit concurrency on the sending function or worker to a number your provider accepts.
• Handle 429 responses with backoff and jitter. See handling rate limits and outbound retry and backoff.
• Use a queue to smooth bursts instead of letting every event send immediately.

Pitfall 7: secrets and environments#

Functions often run in several environments, and a staging function with a production key can email real customers.

Fix:

• Store keys in the platform's secret manager, not in code or build logs. See email API key security.
• Use separate keys per environment and per service, scoped to sending.
• In staging, use recipient allowlists or a sandbox. See keeping staging from emailing real customers.

Pitfall 8: no visibility#

When functions fail, logs are scattered, and sends are hard to trace.

Fix:

• Log a message id and your own correlation id on every send, plus the outcome.
• Record each message's status in a table, updated by webhooks when it is delivered, bounced or complained about.
• Alert on error rates and on queue depth.

A pattern that works#

For most products, this layout is reliable:

1. An event happens (signup, payment, schedule).
2. The handler writes an outbox row with the email type, recipient, template data and an idempotency key, in the same transaction as the event if you can.
3. It returns quickly. The user is not waiting on email.
4. A worker function or a queue consumer reads outbox rows, sends them through the provider's API with the key and updates the status.
5. Retries use backoff, with a cap and a dead-letter state for repeated failure.
6. Webhooks update delivery status, and a small dashboard shows pending, sent and failed.

If you need a delayed send, such as "tomorrow at 9", schedule it in your own system rather than relying on a function that sleeps. See scheduling emails across time zones.

Testing#

• Simulate a timeout after success and check that a retry does not send twice.
• Simulate a provider error and check backoff.
• Fire many events at once and check the concurrency limit.
• Kill a worker mid-send and check that the row is picked up again.

Key takeaways#

• A function may stop as soon as it returns, so never leave a send unfinished after the response.
• Move sending out of the request path with an outbox and a queue.
• Make every send idempotent, because platforms retry and timeouts hide success.
• Use an HTTP API, reuse clients, set explicit timeouts and limit concurrency.
• Keep secrets, environments and logs tidy so failures are visible and safe.