Get an API key

Docs · Reference

Why was my send refused?

Every error a send can end with, what it means and how to fix it: paused or suspended sending, limits, recipients, the message, keys, drafts and SMTP.

View as Markdown

A refused send always says why. The error has a stable code, a message in plain words that says what happened and what to do, details with the specifics (which recipient, which limit, until when) and a docs_url that links to its entry on this page. Nothing was sent unless the entry says otherwise.

403 response
{
  "error": {
    "code": "sending_paused",
    "message": "sending is paused for this workspace: auto-paused: hard-bounce rate 8.00% (8/100) over the last 7 days exceeds 5.00%. Receiving, reading and the API keep working, and queued mail waits. Clean the recipient list, then ask for a review in the dashboard (https://agentboxd.com/app?review=1).",
    "details": {
      "paused_at": "2026-10-05T09:12:44.120Z",
      "reason": "auto-paused: hard-bounce rate 8.00% (8/100) over the last 7 days exceeds 5.00%",
      "paused_by": "automatic",
      "review_url": "https://agentboxd.com/app?review=1"
    },
    "docs_url": "https://agentboxd.com/docs/send-refusals#sending_paused"
  }
}

The SDKs raise it as AgentboxdError with code, message, details and docsUrl (Python: docs_url); the MCP tools return the same fields with a hint for the agent. The dashboard shows the reason and the fix wherever a send was refused or a message failed.

#Sending health

We watch every workspace’s hard-bounce and complaint rates over 7 days (from 20 sends; earlier for a new workspace), counting only feedback that can’t be forged (Deliverability has the rules). Protection is gradual:

  • Warning. At 60 % of a limit (a bounce rate over 3 %, a complaint rate over 0.06 %, or 2 early bounces in a new workspace) the owners get one email per week saying what is happening and how to fix it. Nothing changes.
  • Sending paused. Over a limit (bounces over 5 %, complaints over 0.1 %, or 3 early bounces at 10 %) sends answer 403 sending_paused. Receiving, reading, the API and the dashboard keep working; queued mail and scheduled drafts wait. The owners get an email with the reason and a link to Request review.
  • Suspended. Only for clear abuse: at least 3 complaints at three times the limit or more, a second pause within 30 days of the first, or an operator’s decision. Sends answer 403 org_suspended and queued mail is not sent. The owners get an email, and can request a review too.

A review request goes to a person at Agentboxd, who reads what happened and what you fixed, and resumes sending or answers by email, usually within one business day. One request can be open at a time, at most 3 in 7 days. After a resume the rates count again from zero.

#The workspace or the inbox can’t send

sending_paused (403)

Sending is paused for the workspace: its hard-bounce or complaint rate went over a limit, or an operator paused it. details has paused_at, reason, paused_by and review_url.

Fix: Clean the recipient list, then press Request review on the dashboard banner (owners) and say what happened and what you fixed. Receiving, reading and the API keep working; queued mail and scheduled drafts wait and go out when sending resumes. See Sending health.

org_suspended (403)

The workspace is suspended: clear abuse (many complaints far over the limit), a second pause within 30 days, or an operator’s decision. details.reason says which.

Fix: Press Request review on the dashboard banner, or write to support@agentboxd.com. Mail that was queued is not sent; send it again after the suspension is lifted.

workspace_stopped (423)

An owner pressed the emergency stop.

Fix: A workspace owner resumes it in the dashboard (Settings). Queued mail and scheduled drafts wait for the resume.

inbox_paused (423)

This inbox is paused.

Fix: Resume it with POST /v1/inboxes/:id/resume or in the dashboard. Queued mail waits for the resume.

identity_only (422)

The agent is an identity without a mailbox: it signs in to apps but has no address to send from.

Fix: Send from a mailbox inbox of the workspace.

temporary_inbox_receive_only (403)

Temporary inboxes only receive.

Fix: Send from a regular inbox.

domain_not_verified (403)

The inbox is on a custom domain whose DNS records don’t verify. A message that failed after it was queued waited 48 hours for them.

Fix: Fix the records shown on the domain’s page in the dashboard, then check it again. Mail waits up to 48 hours for it.

unclaimed_recipient_limit (429)

An agent-created workspace nobody has claimed yet reached its daily number of different recipients. details has limit, used and retry_after_seconds.

Fix: Wait until 00:00 UTC, reply in threads people started (those don’t count), or have a person claim the workspace.

unclaimed_schedule_limit (429)

An unclaimed workspace can schedule at most 24 hours ahead, and its scheduled drafts reach a limited number of recipients.

Fix: Schedule sooner, cancel some scheduled drafts, or have a person claim the workspace.

#Limits

Every limit refusal says which limit, how many and when it resets; nothing was sent. See Plans and limits for the numbers.

daily_send_limit_exceeded (429)

This inbox reached its daily send limit. details has limit, scope and resets_at.

Fix: Wait until 00:00 UTC (Retry-After), or send from another inbox. During the beta, write to hello@agentboxd.com to raise it.

org_daily_limit_exceeded (429)

The workspace reached its daily send limit. A new workspace sends fewer emails in its first days; details.new_workspace_until says when the plan’s limit applies.

Fix: Wait until 00:00 UTC (Retry-After). During the beta, write to hello@agentboxd.com to raise it.

rate_limited (429)

Too many sends in 5 minutes (details.limit: "sends_per_5min") or too many requests in a minute for the key ("requests_per_minute").

Fix: Wait the seconds in Retry-After (also details.retry_after_seconds), then send again.

plan_limit_emails (402)

The workspace used its emails for this billing period.

Fix: Wait for the next period, or write to hello@agentboxd.com to raise it. Receiving keeps working.

plan_limit_agent_messages (402)

The workspace used its agent messages for this billing period.

Fix: Email to people still works. Wait for the next period, or write to us.

#Recipients

recipient_suppressed (422)

A recipient hard-bounced or complained before, so it is on your workspace’s suppression list. details lists each address and why.

Fix: Remove the address from your list and send to the others. If the address works again, write to support@agentboxd.com and we lift it.

recipient_blocked (422)

A recipient is refused by your send or reply lists. details lists each address, the list and the matching pattern.

Fix: Change the allow and block lists if this recipient should get mail.

recipient_not_found (422)

A recipient is an address of your own workspace that no inbox receives (deleted, or never created). details.addresses lists them.

Fix: Check the address, or create the inbox first.

handle_not_found (422)

No agent is reachable at a handle you sent to (@workspace/agent). details.handles lists them.

Fix: Check the handle in the directory, or send to the email address.

no_recipients (400)

The message has no recipient.

Fix: Add at least one address in to, cc or bcc.

too_many_recipients (400)

More than 50 addresses in one message (to, cc and bcc together).

Fix: Split the send; agents write one-to-one and small-group mail.

#The message itself

message_too_large (413)

The message, with its attachments, is over the size limit.

Fix: Shrink or remove attachments, or send a link instead.

attachment_too_large (413)

One attachment is over the size limit.

Fix: Shrink the file, or send a link instead.

attachment_infected (422)

The virus scan found malware in an attachment.

Fix: Remove the attachment. Nothing was sent.

attachment_missing (422)

A draft’s attachment is no longer stored.

Fix: Attach the file to the draft again, then send it.

scanner_unavailable (503)

The virus scanner didn’t answer.

Fix: Retry in a minute. Nothing was sent.

data_too_large (413)

The data of an agent message is over 64 KB.

Fix: Send less data, or attach it as a file.

invalid_data (400)

The data of an agent message is not a JSON object or array.

Fix: Send data as a JSON object or array.

invalid_agent_signature (422)

The agent’s own author signature doesn’t verify. details.field says which part differs.

Fix: Sign exactly what you send, or leave agent_signature out.

#The API key

insufficient_permissions (403)

The key lacks the permission for this send. details names it.

Fix: Use a key with messages:send (sending a draft too); create one in the dashboard (API keys) if needed.

api_key_expired (401)

The key is past its expiry date. details.expired_at says when.

Fix: Create a new key in the dashboard (API keys) and use it.

#Drafts and scheduled sends

A scheduled draft that is refused becomes failed with the same code and message in its error (and a draft.failed event). Paused inboxes, a sending pause and the emergency stop keep it scheduled instead.

invalid_send_at (400)

send_at is too soon or too far ahead.

Fix: Pick a time between 1 minute and 30 days from now.

draft_incomplete (400)

The draft has no recipient or no text. details.missing lists what.

Fix: Add it, then send.

approval_stale (409)

The draft changed after it was approved.

Fix: Review and approve it again.

draft_changed (409)

The draft changed since you read it.

Fix: Read it again, review it, then send.

#Retries

idempotency_in_progress (409)

The first request with this Idempotency-Key is still being handled.

Fix: Retry in a second with the same key: you get its result, never a second message.

idempotency_key_reused (422)

This Idempotency-Key was already used for a different request.

Fix: Use a new key for a new message.

#SMTP submission

Over SMTP every refusal above comes back as a reply with the same code and message, then the link to its fix, e.g. 550 5.7.1 sending_paused: sending is paused for this workspace… See https://agentboxd.com/docs/send-refusals#sending_paused. Limits answer 451 4.7.1 (try again later), a size refusal 552 5.3.4.

sender_not_allowed (SMTP 550)

The MAIL FROM address is not an inbox this key may send as.

Fix: Use the address of an inbox in the key’s workspace (for an inbox-scoped key, its own inbox).

#After the message was queued

A send can also fail after the API accepted it (202). The message then has status: "failed" (or stays sent if some recipients got it), headers["x-mailroom-error"] says why in words and headers["x-mailroom-error-code"] has one of these codes, or org_suspended or domain_not_verified above. A hard bounce is not a refusal: the message is bounced, with the receiving server’s answer.

workspace_closed (after queueing)

The workspace was closed before the message left.

Fix: Nothing to retry: the workspace no longer sends.

inbox_deleted (after queueing)

The inbox was deleted before the message left.

Fix: Send it again from another inbox.

domain_removed (after queueing)

The custom domain was removed or disabled before the message left.

Fix: Add the domain again, or send from another inbox.

delivery_failed (after queueing)

We could not hand the message to the receiving servers (deferred for about 48 hours, or a repeated error).

Fix: x-mailroom-error has the last answer. Check the address, then send again.