{"slug": "error-handling-patterns-for-email-agents", "title": "Error Handling Patterns for Email Agents", "summary": "Nylas outlines error handling patterns for email agents, distinguishing between synchronous failures (like rate limits) and asynchronous bounces detected via webhooks. The company emphasizes that only 429 errors are retryable, while 400 and 403 errors indicate states requiring manual intervention. For connected mailboxes, the message.bounce_detected webhook provides bounce details, with 5xx codes triggering suppression lists and 4xx codes allowing capped retries.", "body_md": "A REST API fails synchronously — you get a 4xx and handle it on the spot. Email fails on a delay: the send call returns success, and the actual failure shows up minutes later as a bounce. An autonomous agent that only handles the first kind of error is half-built, and the half it's missing is the half that gets its sending paused. Here's the full failure surface for an email agent, and the retry design that survives it.\n\nThe context: agents built on [Agent Accounts](https://developer.nylas.com/docs/v3/agent-accounts/) — hosted mailboxes the agent owns, currently in beta — where the agent itself decides when to send. That autonomy is exactly why error handling can't be an afterthought: a human notices when replies stop landing; a loop doesn't.\n\nSome failures do come back synchronously on the send request, and each maps to a different response from your code:\n\n| Status | Body | What your agent should do |\n|---|---|---|\n`429` |\n`\"rate limit exceeded\"` |\nBack off and retry; raise quotas via policy if it recurs |\n`400` |\n`\"domain is not verified\"` |\nStop — finish domain verification, retrying is pointless |\n`400` |\nText indicating sending is paused for the account | Stop all sends; a reputation pause is in effect |\n`403` |\n`send blocked by abuse restriction` |\nStop and contact support — there's no quota to wait out |\n\nThe pattern worth internalizing: only the `429`\n\nis retryable. The two `400`\n\ns and the `403`\n\nare states, not transient failures, and a naive exponential-backoff-everything loop will hammer an endpoint that can't succeed. The `403`\n\ndeserves special respect — abuse restrictions can be scoped to a sender, a domain, an organization, an application, or a single grant, and Nylas applies the most specific match. An application-level block affects every account under that application, not just the one you sent from. Recovery is a support conversation, not a timer: include the application ID, the grant ID, and one example error response so the abuse team can locate the restriction. The good news is that once it's cleared, sends succeed on the next attempt — there's no propagation delay to wait through.\n\nFor mail sent through connected mailboxes (Google, Microsoft, iCloud, Yahoo — the 4 providers that generate Non-Delivery Reports), the `message.bounce_detected`\n\nwebhook delivers the failure your send call never saw:\n\n```\n{\n  \"type\": \"message.bounce_detected\",\n  \"data\": {\n    \"grant_id\": \"<NYLAS_GRANT_ID>\",\n    \"object\": {\n      \"bounced_addresses\": \"no-such-user@example.com\",\n      \"bounce_reason\": \"The email account that you tried to reach does not exist.\",\n      \"type\": \"mailbox_unavailable\",\n      \"code\": \"550\",\n      \"bounce_date\": \"Mon, 08 Jun 2026 14:21:00 +0000\"\n    }\n  }\n}\n```\n\nThe `code`\n\nfield is the branch point — and note it's a string, so compare `\"550\"`\n\n, not `550`\n\n. Codes in the 500 range are hard bounces: the address is gone, and the only correct move is a suppression list. Codes in the 400 range are soft bounces — full mailbox, throttled server — safe to retry with a cap:\n\n``` python\ndef handle_bounce(obj: dict, suppression: set[str]):\n    address = obj[\"bounced_addresses\"]\n    if obj[\"code\"].startswith(\"5\"):\n        suppression.add(address)        # permanent: never send again\n    else:\n        schedule_retry(address, max_attempts=3)  # temporary: capped retry\n```\n\nTwo blind spots to plan around. Bounce detection works by finding the NDR in the sender's mailbox, so standard IMAP and Exchange (EWS) accounts — which don't reliably generate NDRs — produce no `message.bounce_detected`\n\nevents at all. And detection is asynchronous by nature: the NDR can arrive minutes after the original send, so your handler can't assume any ordering relative to the send call that caused it.\n\nFor Agent Account sends specifically, the deliverability signal comes through 4 transactional triggers instead: `message.transactional.delivered`\n\n, `.bounced`\n\n, `.complaint`\n\n, and `.rejected`\n\n. Subscribe to all of them — they're your only real-time window into the rates described next.\n\nThis is where error handling stops being per-message and becomes per-account. Nylas tracks each Agent Account's rolling bounce and complaint rates, with explicit thresholds documented in the [usage limits guide](https://developer.nylas.com/docs/v3/agent-accounts/send-limits/):\n\nThe measurement details change how you design around these. The bounce rate counts only hard bounces to addresses that don't exist — full mailboxes, greylisting, and other transient rejections don't touch it — so a suppression list directly protects the metric. The denominator is a recent representative send volume rather than a fixed time window, which keeps the rate meaningful whether the account sends a hundred messages a day or a million. Complaints are counted only against recipient domains that send complaint feedback to senders, meaning your measured 0.1% likely understates real spam-folder activity.\n\nOne more asymmetry matters operationally: \"under review\" is completely silent to your application. Sending continues, no error changes shape, and the only place the trend is visible is your own webhook-derived telemetry. By the time the API starts returning the pause response, the silent phase is already over. And a pause doesn't clear itself on a timer — it requires contacting support with the cause and the fix. The cheap-looking shortcut of \"just retry everything and let the bounces sort themselves out\" converts directly into a multi-day outage for your agent.\n\nThe 0.1% complaint threshold deserves a moment of arithmetic: on a low-volume account, a handful of recipients clicking \"mark as spam\" is enough to land you under review. For an agent doing outreach, honoring unsubscribes immediately isn't politeness — it's uptime.\n\nThe resilient design mirrors what the platform does, one layer earlier:\n\n`429`\n\nwith backoff; halt on pause, verification, and abuse responses.The [bounce handling recipe](https://developer.nylas.com/docs/cookbook/use-cases/build/handle-bounced-email/) covers the webhook wiring end to end.\n\nStart with the suppression list — it's an afternoon of work and it protects both failure channels at once. Then ask the harder question: if your agent's bounce rate doubled overnight, would anything in your system notice before the 10% line did?", "url": "https://wpnews.pro/news/error-handling-patterns-for-email-agents", "canonical_source": "https://dev.to/qasim157/error-handling-patterns-for-email-agents-1hen", "published_at": "2026-06-16 11:06:12+00:00", "updated_at": "2026-06-16 11:17:15.326355+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models"], "entities": ["Nylas", "Agent Accounts", "Google", "Microsoft", "iCloud", "Yahoo"], "alternates": {"html": "https://wpnews.pro/news/error-handling-patterns-for-email-agents", "markdown": "https://wpnews.pro/news/error-handling-patterns-for-email-agents.md", "text": "https://wpnews.pro/news/error-handling-patterns-for-email-agents.txt", "jsonld": "https://wpnews.pro/news/error-handling-patterns-for-email-agents.jsonld"}}