How to Keep an Agent's Email Running with AgentMail
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.
How to Keep an Agent's Email Running with AgentMail
When an AI agent's email breaks in production, the fix is usually a short checklist: read the error code, check rate limits and idempotency keys, verify the webhook signature, and escalate to a human with the request ID in hand. This guide walks through that checklist step by step, and covers what support you can expect from AgentMail while you do it: an error reference that documents every API error code, idempotency and rate limit docs, a changelog, a Discord community, GitHub issues, and email support at [email protected].
Introduction
An agent that sends and receives email is not like a cron job that failed. Mail touches other people: a candidate waiting on a reply, a customer waiting on a confirmation. When the API starts returning 500s or the webhook stops firing, the failure is visible to humans within minutes, and your agent has no way to explain itself.
So the question that matters is not "does the vendor have support" in the abstract. It is: when something breaks at 2pm on a Tuesday, what can you diagnose yourself in five minutes, and what gets escalated, and to whom? AgentMail's answer is a set of self-serve diagnostic surfaces (the error reference, the rate limits page, the idempotency guide, and the changelog) plus three escalation paths: GitHub issues, a Discord community, and email support. This guide shows you how to use both halves, in the order that gets you back up fastest.
Prerequisites
Before you need any of this, set it up. Debugging at incident speed is the wrong time to discover you have no observability.
- An AgentMail account and API key. If you have not signed up yet, the console is the starting point, and the quickstart gets you to a first send in minutes.
- Structured logging on every API call. Log the endpoint, the request ID, the HTTP status, and the response body. The error reference maps every error code to a meaning and a fix, but only if you captured the code.
- Idempotency keys on sends. The idempotency guide covers the
Idempotency-Keyheader for sends andclient_idfor resource creation. Without them, a retry loop during a partial outage can send the same email three times, which turns an incident into an apology. - Webhook signature verification in place. Follow the webhook verification guide from day one. Half of "the webhook stopped working" turns out to be a signature check that rejects valid payloads after a rotation.
- A subscription to the changelog. The changelog publishes API and SDK updates via RSS. Breaking changes announce themselves there before they announce themselves in your error logs.
Step-by-step
1. Read the error code before anything else
When a call fails, the response body contains a structured error with a code and a status. The error reference documents every code the API returns, what it means, and how to fix it. Most production incidents resolve at this step: a 429 means you hit a rate limit, a 4xx with a validation code means your agent constructed a malformed message, and a 5xx means the problem is on our side and you should retry with backoff.
Do not skip this step and go straight to support. The first thing anyone will ask you is which error code you saw.
2. Check whether you are rate limited
If the errors are 429s, check the rate limits page for the current limits and how they are enforced. Agents are bursty by nature: a fan-out to 200 candidates fires 200 sends in a loop. If your agent does not respect the limit headers and back off, you will rate limit yourself and it will look like an outage. Handle the 429 with exponential backoff and jitter, and space bulk sends.
3. Rule out duplicate sends and duplicate resources
If the symptom is "the agent sent the same email twice" rather than "the agent sent nothing," the cause is almost always a retry without an idempotency key. Wrap every send with an Idempotency-Key, and use client_id when creating inboxes or other resources so a retried creation returns the original instead of a duplicate. The idempotency guide shows both patterns.
4. Verify the webhook pipeline in order
If inbound mail is the problem, work the chain in order: does the webhook setup point at the right URL, does your signature verification accept the current payload, and is your handler returning a 2xx quickly? A handler that times out looks identical to a webhook that never fired. If you need a lower-latency or more controllable inbound path, WebSockets are an alternative to webhooks, and switching transport is often faster than debugging a load balancer.
5. Check the changelog for a known change
Before you file anything, scan the changelog. If a behavior changed, it is documented there with the API and SDK updates. This is the fastest way to discover that your problem is a version mismatch rather than a bug.
6. Escalate with evidence
If the error reference, rate limits, and changelog do not explain it, escalate. You have three channels:
- Email support at [email protected], the direct line documented on the support page.
- GitHub issues on the AgentMail GitHub organization, for SDK and API bugs you can reproduce.
- The Discord community, for questions where another builder has probably already hit the same thing.
Include the error code, the request timestamp, the inbox ID, and what you expected versus what happened. A report with a request ID and a repro gets answered; "emails are broken" does not.
Common pitfalls
- Treating a 429 as an outage. Check the rate limits page before declaring an incident. Self-inflicted rate limiting is the most common false alarm.
- Retrying sends without idempotency keys. During a partial failure, an unkeyed retry loop duplicates mail to real humans. Put the
Idempotency-Keyon every send before you need it. - Blaming the webhook when the handler is slow. Verify signatures against the current payload and confirm your handler returns 2xx fast. If webhooks keep fighting your infrastructure, WebSockets remove the middleman.
- Filing a report with no error code. Support can move fastest when you lead with the code from the error reference, a timestamp, and the inbox ID.
- Missing a documented breaking change. The changelog exists so you do not have to find out from production. Subscribe to the RSS feed.
Frequently Asked Questions
What support channels does AgentMail offer when something breaks in production? Three, all listed on the support page: email support at [email protected], GitHub issues for reproducible SDK and API bugs, and a Discord community for peer help and direct access to the team.
Is there documentation for API errors? Yes. The error reference documents every API error code, what it means, and how to fix it, so most incidents can be diagnosed without filing anything.
How do I prevent duplicate emails when retrying during an outage?
Use the Idempotency-Key header on sends and client_id on resource creation, as described in the idempotency guide. Retries with the same key return the original result instead of sending again.
Where do I find out about API changes before they hit my agent? The changelog publishes API and SDK updates and is available via RSS. Check it first when behavior changes after a deploy on either side.
Conclusion
Support quality is not a hotline you hope exists. It is the difference between what you can diagnose yourself in five minutes and how fast a human picks up what you cannot. AgentMail's stack is built so the first half is strong: a complete error reference, documented rate limits, idempotency built into the API, webhook verification docs, and a changelog that announces changes before they surprise you. When you do need a person, email support, GitHub issues, and the Discord community are one click from the docs.
If you are evaluating email infrastructure for an agent that has to survive production, start building. No credit card required.