Skip to main content
When an email bounces, Lettr provides structured data about the failure — including a bounce type, category, SMTP response code, and human-readable message. This guide explains how to read that data and respond appropriately.

​
Hard vs Soft Bounces

Lettr classifies every bounce as either hard or soft. The distinction determines how the platform handles the failure automatically and what action you should take.

​
Hard Bounces

A hard bounce is a permanent delivery failure. The recipient’s mail server has definitively rejected the email, and retrying will not succeed. Lettr automatically suppresses hard-bounced addresses so you never send to them again. Examples: The email address does not exist, the domain has no mail server, or the recipient has permanently blocked your sender.

​
Soft Bounces

A soft bounce is a temporary delivery failure. The email may be deliverable if retried later. Lettr automatically retries soft bounces up to 3 times with exponential backoff before giving up. Examples: The recipient’s mailbox is full, the server is temporarily unavailable, or the message was rate-limited.
If a soft bounce continues to fail after all retry attempts, Lettr records a final bounce event. Addresses that repeatedly soft bounce over time may eventually be suppressed.

​
Bounce Categories Reference

Every bounce event includes a bounceCategory that describes the specific reason for the failure. Use this table to determine the correct response for each category.
CategoryTypeDescriptionRecommended Action
invalid_addressHardThe email address does not exist or is permanently invalidRemove from your list immediately
domain_not_foundHardThe domain does not exist or has no configured mail serverRemove from your list immediately
mailbox_fullSoftThe recipient’s mailbox has exceeded its storage quotaWait for automatic retry; no immediate action needed
blockedHardThe recipient or their mail server has blocked delivery from your senderInvestigate the cause and remove the address
spam_relatedHardThe message was rejected by spam filters or content policiesReview your email content and sender reputation
policy_relatedHardThe receiving server rejected the message due to administrative policyContact the recipient through another channel if needed
server_errorSoftA temporary server-side issue prevented deliveryWait for automatic retry; no immediate action needed
protocol_errorSoftA technical problem occurred during the SMTP transactionWait for automatic retry; no immediate action needed
unknownVariesThe bounce could not be classified into a known categoryReview the bounceCode and message fields manually

​
SMTP Response Code Reference

The bounceCode field in bounce events contains the SMTP response code returned by the recipient’s mail server. These codes provide additional detail beyond the bounce category.

​
Temporary Failures (4xx)

These codes indicate a temporary issue. Lettr automatically retries delivery for these responses.
CodeMeaningTypical Cause
421Server temporarily unavailableThe receiving server is down, overloaded, or restarting
450Mailbox unavailable (busy)The mailbox exists but is temporarily locked or in use
452Insufficient storageThe recipient’s mailbox is full or the server is out of disk space

​
Permanent Failures (5xx)

These codes indicate a permanent failure. The address should be removed from your list or the issue investigated.
CodeMeaningTypical Cause
550 5.1.1User unknown / mailbox not foundThe email address does not exist on the receiving server
550 5.1.2Bad destination domainThe domain exists but is not configured to receive email
550 5.7.1Message rejected (policy/spam)The message was blocked due to content filtering or sender policy
551User not localThe recipient is not hosted on that server and forwarding was refused
552Message too largeThe email exceeded the recipient server’s size limit
553Invalid mailbox nameThe email address format is syntactically invalid
554Transaction failedA general rejection — check the full message field for details
SMTP response codes alone do not tell the full story. Always read the message field in the bounce event for the specific reason provided by the receiving server.

​
Reading Bounce Webhook Events

The most reliable way to monitor bounces is through webhooks. When an email bounces, Lettr sends an email.bounced event to your configured webhook endpoint.

​
Event Payload

{
  "id": "evt_abc123",
  "type": "email.bounced",
  "createdAt": "2024-01-15T10:30:05Z",
  "data": {
    "emailId": "email_123",
    "requestId": "req_456",
    "to": "invalid@nonexistent.com",
    "bounceType": "hard",
    "bounceCategory": "invalid_address",
    "bounceCode": "550",
    "message": "550 5.1.1 The email account that you tried to reach does not exist",
    "bouncedAt": "2024-01-15T10:30:05Z"
  }
}

​
Webhook Handler

This handler processes bounce events, updates your subscriber records, and alerts your team when reputation-threatening bounces occur: 
app.post('/webhooks/lettr', async (req, res) => {
  const event = req.body;

  if (event.type === 'email.bounced') {
    const { to, bounceType, bounceCategory, bounceCode, message } = event.data;

    // Log every bounce for analysis
    await logBounce({
      email: to,
      type: bounceType,
      category: bounceCategory,
      code: bounceCode,
      message: message,
      timestamp: new Date()
    });

    if (bounceType === 'hard') {
      // Mark the subscriber as bounced in your database
      await db.subscribers.update({
        where: { email: to },
        data: {
          status: 'bounced',
          bounceCategory: bounceCategory,
          lastBounceAt: new Date()
        }
      });

      // Alert the team for spam or block bounces
      if (bounceCategory === 'spam_related' || bounceCategory === 'blocked') {
        await notifyTeam({
          type: 'reputation_concern',
          email: to,
          reason: message
        });
      }
    }

    if (bounceType === 'soft') {
      // Track soft bounces — suppress after repeated failures
      await db.subscribers.update({
        where: { email: to },
        data: {
          softBounceCount: { increment: 1 },
          lastSoftBounceAt: new Date()
        }
      });
    }
  }

  res.sendStatus(200);
});

​
Out-of-Band Bounces

Some bounces arrive asynchronously, well after the initial delivery attempt appeared to succeed. These are called out-of-band (OOB) bounces. They occur when the receiving server initially accepts the message but later discovers it cannot be delivered — for example, when a forwarding address turns out to be invalid. Lettr sends these as email.out_of_band events: 
{
  "id": "evt_oob789",
  "type": "email.out_of_band",
  "createdAt": "2024-01-15T11:00:00Z",
  "data": {
    "emailId": "email_123",
    "requestId": "req_456",
    "to": "recipient@example.com",
    "reason": "552 5.2.2 Mailbox full",
    "bouncedAt": "2024-01-15T11:00:00Z"
  }
}
Handle out-of-band bounces the same way you handle regular bounces. Update your subscriber records and suppress the address if the failure is permanent: 
if (event.type === 'email.out_of_band') {
  const { to, reason } = event.data;

  await logBounce({
    email: to,
    type: 'out_of_band',
    message: reason,
    timestamp: new Date()
  });

  // Treat as a hard bounce — update your records
  await db.subscribers.update({
    where: { email: to },
    data: {
      status: 'bounced',
      lastBounceAt: new Date()
    }
  });
}

​
Deferred Emails

A deferred email is not a bounce — it is a temporary delay. The receiving server has asked Lettr to try again later, usually because of rate limiting or temporary unavailability. Lettr tracks these as email.deferred events. 
{
  "id": "evt_jkl012",
  "type": "email.deferred",
  "createdAt": "2024-01-15T10:30:05Z",
  "data": {
    "emailId": "email_123",
    "requestId": "req_456",
    "to": "recipient@example.com",
    "reason": "421 Server temporarily unavailable",
    "retryCount": 1,
    "nextRetryAt": "2024-01-15T10:45:00Z",
    "deferredAt": "2024-01-15T10:30:05Z"
  }
}
Lettr handles retries automatically with exponential backoff. You do not need to take action on individual deferral events. When to investigate deferrals:
  • A large number of emails to the same domain are being deferred — this may indicate that the receiving server is throttling you due to reputation concerns or volume limits.
  • Emails to a specific recipient are deferred repeatedly across multiple sends — the receiving server may have a persistent issue.
  • Your overall deferral rate spikes suddenly — check whether you recently increased sending volume or changed your content.

​
Reducing Your Bounce Rate

Check for valid syntax, common typos (e.g., gmial.com), and disposable email providers at the point of signup. Catching invalid addresses before they enter your list prevents bounces entirely.
Require new subscribers to confirm their email address by clicking a link in a verification email. This ensures the address is real, reachable, and owned by the person who signed up.
Set up webhook handlers to process email.bounced and email.out_of_band events as they arrive. Remove hard-bounced addresses from your sending lists immediately rather than waiting for a batch cleanup.
Remove subscribers who have not opened or clicked any email in the past 6 to 12 months. Inactive addresses are more likely to become invalid over time as people abandon mailboxes.
Track your bounce rate in the Lettr dashboard after every send. If you notice an upward trend, investigate immediately rather than waiting for it to reach critical levels.

​
Bounce Rate Guidelines

Use these thresholds to assess the health of your sending practices:
Bounce RateStatusWhat to Do
Below 2%HealthyYour list hygiene is good. Continue current practices and monitor regularly.
2% to 5%WarningReview your list for stale or unvalidated addresses. Implement double opt-in if you haven’t already. Check recent list imports for quality issues.
Above 5%CriticalStop sending to unverified segments immediately. Clean your entire list by removing unengaged and invalid addresses. Investigate the source of bad addresses before resuming normal volume.
ISPs closely monitor bounce rates. A bounce rate consistently above 5% can result in your domain being throttled or blocked entirely. Address bounce rate problems before they escalate.

Bounces

Bounce types, categories, and automatic handling

Webhook Event Types

Complete reference for all webhook events

List Hygiene

Maintain healthy recipient lists

Delivery Issues

Troubleshoot common delivery problems