Suppression Lists

What is a Suppression List?

A suppression list contains email addresses that should not receive emails. This includes:

• Hard bounces - Invalid or non-existent addresses
• Spam complaints - Recipients who marked your email as spam
• Unsubscribes - Recipients who opted out

Why Suppressions Matter

Protect Your Reputation

Sending to invalid addresses damages your sender reputation:

• ISPs track bounce rates
• High bounce rates = spam folder
• Spam complaints can get you blacklisted

Save Money

Don't pay to send emails that will never be delivered.

Legal Compliance

Many regulations require honoring unsubscribe requests:

• CAN-SPAM (US)
• GDPR (EU)
• CASL (Canada)

Suppression Types

Hard Bounces

Permanent delivery failures:

• Email address doesn't exist
• Domain doesn't exist
• Mailbox is disabled

Hard bounces are automatically added to the suppression list.

Soft Bounces

Temporary delivery failures:

• Mailbox full
• Server temporarily unavailable
• Message too large

Soft bounces are retried automatically and only suppressed after multiple failures.

Spam Complaints

When recipients click "Report Spam":

• ISPs send feedback loop reports
• Address is immediately suppressed
• Reduces future complaints

Manual Unsubscribes

When recipients unsubscribe:

• Via unsubscribe link in email
• Via preference center
• Via direct request

Managing Suppressions

View Suppression List

1. Go to Email > Servers > [Server] > Suppressions
2. Filter by type: Bounces, Complaints, Unsubscribes
3. Search for specific addresses

Add Suppression

await client.suppressions.create({
  serverId: 'srv_123',
  email: 'user@example.com',
  reason: 'manual',
  comment: 'User requested removal',
});

Remove Suppression

Only remove suppressions if you're confident the address is valid:

await client.suppressions.delete({
  serverId: 'srv_123',
  email: 'user@example.com',
});

Bulk Import

Import suppressions from a CSV file:

email,reason,comment
user1@example.com,bounce,Hard bounce
user2@example.com,complaint,Spam complaint
user3@example.com,unsubscribe,User requested

Automatic Suppression

Enable Auto-Suppression

Configure in server settings:

1. Go to Email > Servers > [Server] > Settings
2. Enable Auto-suppress hard bounces
3. Enable Auto-suppress spam complaints

Suppression at Send Time

When you send an email, we check the suppression list:

const result = await client.emails.send({
  from: 'hello@yourapp.com',
  to: 'suppressed@example.com',
  subject: 'Hello',
  html: '<p>Content</p>',
});
 
// result.status = 'suppressed'
// result.reason = 'bounce'

Server-Level vs Stream-Level

Server-Level Suppressions

Apply to all streams in the server. Use for:

• Hard bounces (address is invalid everywhere)
• Spam complaints (don't email this person again)
• Global unsubscribes

Stream-Level Suppressions

Apply only to specific streams. Use for:

• Unsubscribes from specific email types
• Preferences (unsubscribe from marketing but keep transactional)

Handling Bounces

Hard Bounce Workflow

1. Email bounces with permanent error
2. Address added to suppression list
3. Future sends to this address are blocked
4. Webhook notification sent (if configured)

Soft Bounce Workflow

1. Email bounces with temporary error
2. Retry with exponential backoff
3. After 3 failed attempts, treat as hard bounce
4. Add to suppression list

Best Practices

Clean Your Lists

• Import existing bounce lists when migrating
• Regularly review and clean old addresses
• Remove inactive subscribers

Handle Bounces Promptly

// Webhook handler for bounces
app.post('/webhooks/email', (req, res) => {
  const event = req.body;
 
  if (event.event === 'bounced' && event.bounceType === 'hard') {
    // Update your database
    await db.users.update({
      where: { email: event.to },
      data: { emailStatus: 'invalid' },
    });
  }
 
  res.status(200).send('OK');
});

Provide Unsubscribe Options

Always include an unsubscribe link:

<a href="{{unsubscribe_url}}">Unsubscribe</a>

Don't Remove Suppressions Blindly

Only remove suppressions when:

• User confirms their address is valid
• You've verified the domain exists
• Sufficient time has passed (for soft bounces)

Suppression Export

Export your suppression list for backup or migration:

1. Go to Suppressions
2. Click Export
3. Download CSV file

API Reference

// List suppressions
const suppressions = await client.suppressions.list({
  serverId: 'srv_123',
  type: 'bounce', // optional filter
  limit: 100,
});
 
// Check if email is suppressed
const status = await client.suppressions.check({
  serverId: 'srv_123',
  email: 'user@example.com',
});
 
if (status.suppressed) {
  console.log(`Suppressed: ${status.reason}`);
}

Next Steps

• Bounces - Understanding bounce types
• Best Practices - Improve deliverability
• Webhooks - Handle bounce events