Questions · Updated 2026-09-23

Why did my email bounce?

An email bounced when the receiving server refused it. GET /emails/{id}/explain returns verdict bounce, and the email.bounced event from GET /emails/{id}/events carries the diagnostic the server sent.

An email bounced when the receiving server refused it. GET /emails/{id}/explain returns verdict bounce. A permanent refusal says "The recipient server refused this address permanently — the address is dead or never existed." A temporary refusal says "The recipient server refused this message temporarily — the address is likely fine." GET /emails/{id}/events has the email.bounced event, and its diagnostic_code is the server's own words.

The four classes

Every bounce lands in one class. The meaning and the fix are on the docs page, and the Deliverability screen links to the same ids:

  • hard — the receiving server says the address does not exist.
  • soft — a temporary refusal, such as a full mailbox or greylisting.
  • block — refused on reputation or content, not on the address.
  • policy — the address is real, and this message was refused for size, an attachment, or the suppression list.

Deliverability states that hard bounces and complaints add the recipient to the suppression list. GET /suppressions lists the address and why. A later POST /emails to a suppressed address is refused with suppressed_recipient.

curl -sS -X GET https://api.agentisend.com/emails/9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42/explain \
  -H "Authorization: Bearer $AGENTISEND_API_KEY"
200
{
  "actions": [],
  "evidence": "string",
  "id": "9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42",
  "retryable": true,
  "status": "string",
  "verdict": "string",
  "what_happened": "string"
}
Response

What to change

Read diagnostic_code before changing anything else. GET /emails/{id}/explain sets retryable to false when it uses the permanent sentence, and true when it uses the temporary one. The class fixes are the ones on /docs: a hard bounce is already on the suppression list, a soft bounce is retried, a block is the class that ends in a blocklist, and a policy bounce is the message — shrink it, drop the attachment, or inspect GET /suppressions when the reason is suppression.

No sentence here is an inbox-placement rate.

Next