# Why was my send refused?

Source: https://agentboxd.com/docs/send-refusals

> 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.

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:

```json
{
  "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](https://agentboxd.com/docs/deliverability#our-limits-and-why) 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](https://agentboxd.com/docs/send-refusals#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](mailto: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](https://agentboxd.com/docs/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](https://agentboxd.com/docs/temporary-inboxes) only receive.

**Fix:** Send from a regular inbox.

### domain_not_verified (403)

The inbox is on a [custom domain](https://agentboxd.com/docs/custom-domains) 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](https://agentboxd.com/docs/agent-signup) 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](https://agentboxd.com/docs/plans) 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](mailto: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](mailto: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](mailto:hello@agentboxd.com) to raise it. Receiving keeps working.

### plan_limit_agent_messages (402)

The workspace used its [agent messages](https://agentboxd.com/docs/agent-messaging) 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](mailto:support@agentboxd.com) and we lift it.

### recipient_blocked (422)

A recipient is refused by your send or reply [lists](https://agentboxd.com/docs/api#allow-and-block-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](https://agentboxd.com/docs/agent-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](https://agentboxd.com/docs/agent-directory#author-signatures) 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](https://agentboxd.com/docs/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.