Skip to main content

​
Managing Bounces

Understand and manage bounced email addresses to maintain list hygiene.

​
Bounce Types

​
Hard Bounces

Permanent delivery failures - addresses are automatically suppressed.
CategoryCauseAction
invalid_addressAddress doesn’t existAuto-suppress
domain_not_foundDomain doesn’t existAuto-suppress
blockedRecipient blocked senderAuto-suppress

​
Soft Bounces

Temporary delivery failures - Lettr retries automatically.
CategoryCauseAction
mailbox_fullRecipient’s inbox is fullRetry
server_errorReceiving server issueRetry
rate_limitedToo many emails sentRetry with backoff

​
View Bounces

const bounces = await lettr.bounces.list({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  type: 'hard'
});

bounces.forEach(bounce => {
  console.log({
    email: bounce.email,
    type: bounce.type,
    category: bounce.category,
    message: bounce.message,
    bouncedAt: bounce.createdAt
  });
});

​
Bounce Statistics

const stats = await lettr.stats.get({
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

console.log({
  totalSent: stats.sent,
  totalBounced: stats.bounced,
  hardBounces: stats.hardBounces,
  softBounces: stats.softBounces,
  bounceRate: stats.bounceRate
});

​
Bounce Rate Guidelines

RateStatusAction
< 2%HealthyMaintain current practices
2-5%WarningReview list hygiene
> 5%CriticalClean list immediately

​
Clean Your List

Remove bounced addresses from your mailing list: 
// Get all hard bounces
const bounces = await lettr.bounces.list({
  type: 'hard',
  limit: 1000
});

// Remove from your database
for (const bounce of bounces) {
  await yourDatabase.subscribers.delete({
    email: bounce.email
  });
}

​
Re-Enable a Bounced Address

If you’re certain an address is now valid: 
await lettr.suppressions.delete('previously-bounced@example.com');
Only remove bounce suppressions if you have strong evidence the address is now valid. Sending to known bad addresses hurts your reputation.

​
Bounce Webhooks

Handle bounces in real-time: 
app.post('/webhooks/lettr', (req, res) => {
  const event = req.body;
  
  if (event.type === 'email.bounced') {
    const { to, bounceType, bounceCategory } = event.data;
    
    if (bounceType === 'hard') {
      // Update your database
      markAsInvalid(to);
      
      // Notify relevant team
      notifyTeam(to, bounceCategory);
    }
  }
  
  res.sendStatus(200);
});

​
Prevent Bounces

Confirm email addresses before adding to your list.
Use email validation when collecting addresses.
Remove inactive subscribers periodically.
Stop sending to recipients who never engage.

​
Email Validation

Validate addresses before adding to your list: 
const validation = await lettr.validate('user@example.com');

if (validation.valid) {
  // Safe to add to list
} else {
  console.log(`Invalid: ${validation.reason}`);
}