Bounces

When an email cannot be delivered, the receiving server sends a bounce. MailLand classifies bounces, automatically suppresses addresses that will never accept mail, and retries transient failures.

Bounce TypesCopy Anchor Link

Bounce CategoriesCopy Anchor Link

The bounce-breakdown API (GET /v1/deliverability/bounce-breakdown) groups every bounce by the classification the mail transfer agent itself assigns to the SMTP rejection, then maps that classification to hard, soft or blocked. The table below is the complete, pinned production vocabulary: anything the host emits that isn't in it is counted as unknown rather than guessed at:

Two endpoints further down this page report bounces in a vocabulary of their own. /v1/transactional/bounces/statistics counts hardBounces and softBounces from the same decision that suppresses (or does not suppress) the address, so a blocked bounce is never counted as hard or soft; its byCategory groups the host classification above into a coarser set (invalid_recipient, bad_mailbox, bad_domain, mailbox_full, content_rejected, policy_reason, general_bounce). /v1/transactional/bounces/recent returns each message's host classification itself as bounceCategory.

Automatic HandlingCopy Anchor Link

Hard bouncesCopy Anchor Link

1. The recipient email is immediately added to the global suppression list
2. All future emails (transactional and marketing) to this address are blocked
3. A message.bounced webhook event is fired with bounce_type: "hard" (no separate suppression.added event is emitted)

Soft bouncesCopy Anchor Link

1. The message status becomes Bounced
2. The address is suppressed for Marketing mail for 30 days (transactional mail is still delivered): on the first soft bounce, not after retries. Exception: an address's first MessageExpired bounce, or its first message-too-large bounce (QuotaIssues with the enhanced code 5.3.4 or 5.2.3), suppresses nothing; another one within 30 days suppresses as usual.
3. A message.bounced webhook event is fired with bounce_type: "soft". (Temporary failures are retried by the MTA itself before a bounce is reported to MailLand.)
4. After 30 days, the suppression expires automatically

Blocked bouncesCopy Anchor Link

1. The message status changes to Bounced (Failed for an AdminBounce), but the recipient's address is not added to any suppression list: a blocked bounce is a statement about our sending, not about the recipient's mailbox
2. A message.bounced webhook event is fired with bounce_type: "blocked" (for an AdminBounce, a message.failed event with reason: "admin_bounce" instead)
3. A sustained rate of blocked bounces raises an internal alert for manual review; there is no automatic pause of sending

Bounce StatisticsCopy Anchor Link

Get aggregate bounce statistics for a time period:

GET https://api.mail.land/v1/transactional/bounces/statistics

Authenticate with Authorization: Bearer <token> or X-API-Key: <api key>.

curl https://api.mail.land/v1/transactional/bounces/statistics \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "totalBounces": 1125,
  "hardBounces": 450,
  "softBounces": 385,
  "generalBounces": 290,
  "byCategory": {
    "invalid_recipient": 380,
    "mailbox_full": 345,
    "content_rejected": 185,
    "policy_reason": 95,
    "bad_domain": 70,
    "general_bounce": 50
  }
}

Recent BouncesCopy Anchor Link

Get the most recent bounced messages:

GET https://api.mail.land/v1/transactional/bounces/recent?limit=50

curl "https://api.mail.land/v1/transactional/bounces/recent?limit=50" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

[
  {
    "messageId": "t_a1b2c3d4e5f6",
    "recipientEmail": "[email protected]",
    "subject": "Your order has shipped",
    "bounceCategory": "InvalidRecipient",
    "bounceReason": "550 5.1.1 The email account does not exist",
    "bouncedAt": "2026-02-17T12:34:56Z",
    "retryCount": 0
  },
  {
    "messageId": "t_d4e5f6a1b2c3",
    "recipientEmail": "[email protected]",
    "subject": "Invoice #1234",
    "bounceCategory": "QuotaIssues",
    "bounceReason": "552 5.2.2 Mailbox full",
    "bouncedAt": "2026-02-17T11:00:00Z",
    "retryCount": 2
  }
]

Results are ordered by bouncedAt descending, limited to the last 90 days. bouncedAt is the message's creation time, not a separately tracked bounce timestamp.

Retry a Bounced MessageCopy Anchor Link

Manually retry delivery of a bounced message:

POST https://api.mail.land/v1/transactional/bounces/{messageId}/retry

curl -X POST https://api.mail.land/v1/transactional/bounces/t_a1b2c3d4e5f6/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

The retry re-sends the original content through MailLand's outbox. Open and click tracking are OFF on retried copies: the original send's tracking choice isn't recoverable from the message row.

Bounce Rate ThresholdsCopy Anchor Link

Thresholds are plan defaults, evaluated once at least the minimum sample size of sends has occurred in the evaluation window:

Sending is paused (API 429) when the pause threshold is reached; this lowers your sender score as well.

Deliverability HoldsCopy Anchor Link

A pause-threshold breach also places a durable deliverability hold on the workspace, separate from the transient 429 pause above. While a hold is active, every send, transactional and marketing alike, is refused: 403 ACTION_REQUIRED from the API, a temporary 451 4.7.0 over SMTP relay, so your mail server keeps the message queued and retries.

• The hold is placed once per breach episode, not repeated on every send.
• It persists until MailLand support reviews and lifts it; a recovering bounce or complaint rate does not lift it automatically, there is no auto-lift.
• The workspace's Owners and Admins receive an email as soon as the hold is placed.

Best PracticesCopy Anchor Link

• Clean your lists: validate email addresses before sending with Email Validation. Remove addresses that consistently bounce.
• Monitor bounce categories: a spike in content_rejected bounces may indicate a content issue, not a list quality problem.
• Don't retry hard bounces: hard bounces are permanent. Retrying wastes quota and damages reputation.
• Watch soft bounce patterns: repeated mailbox_full bounces from the same domain may indicate a provider-level issue.
• Use the deliverability dashboard: track bounce rates by provider to catch domain-specific problems early.

Next StepsCopy Anchor Link

• Suppressions: manage the suppression list
• Deliverability Overview: monitor sender score and trends
• Webhooks Events: receive message.bounced events