All storiesEngineering

An email API error checklist for production support

Separate invalid requests, authentication failures, quota limits and uncertain sends before deciding what to retry.

Sendar2 min read

Published 24 June 2026 · Updated 4 October 2026

“The email failed” is a starting point, not a diagnosis. The application may have rejected the event, the API may have rejected the request, or the sender may have accepted a message whose later delivery failed. Support is faster when those cases are kept separate.

Capture useful evidence

Record the application event ID, the HTTP status, a redacted error body and any returned Sendar message ID. Keep credentials and message secrets out of logs. The exact response is more useful than a generic exception that only says the request was unsuccessful.

Establish whether a request was actually submitted. An exception while building the payload is not the same as a network timeout after submission. That distinction affects whether another send could produce a duplicate.

Correct configuration failures

A 401 response points to authentication. Check whether the server has the intended key, whether it was revoked and whether the deployed environment was updated. Do not paste the key into a support message or a browser console to investigate.

For validation and permission failures, inspect the sender domain, recipient format, required fields and account restrictions. Template mode and inline mode use different request shapes. Repeating the same invalid payload will not resolve the problem.

Inspect limits and timing

A quota or rate-limit response needs a different response from a malformed message. Check the account allowance and the volume generated by the application. A retry loop that continues immediately can increase load while making no progress.

For a server failure or connection timeout, determine whether the send outcome is known. Reuse a stable idempotency key for the same single-email event and inspect history. Do not generate a new key just to force the request past uncertainty.

Close the loop with the product

Once the technical condition is resolved, verify what the user sees. A completed purchase should not appear failed solely because a receipt could not be submitted. Give operations a way to inspect and deliberately recover missing notifications without changing the underlying business event or repeatedly messaging the recipient.

Keep building

S.
Sendar

Tools and practical advice for application email.