Skip to main content
Suppressions prevent emails from being sent to specific addresses that have bounced, complained, or opted out. Properly managing suppressions is essential for maintaining your sender reputation and ensuring high deliverability.

​
What Are Suppressions?

Suppressed addresses are email addresses that should not receive emails. When you attempt to send to a suppressed address, the email is blocked before delivery to protect your sender reputation. Addresses can be suppressed for several reasons:
ReasonDescriptionHow It’s Added
Hard bounceAddress doesn’t exist or is permanently unreachableAutomatically on bounce
Spam complaintRecipient marked your email as spamAutomatically on complaint
UnsubscribeRecipient opted out via List-UnsubscribeAutomatically on unsubscribe

​
How Suppressions Work

When you send an email through Lettr, the suppression system is involved at multiple stages:
  1. API call — You call the Lettr API to send an email. Lettr forwards the request to the delivery infrastructure, which checks the recipient against the suppression list. If the address is suppressed, the recipient is rejected and included in the rejected count of the API response. The email is never sent.
  2. Delivery attempt — If the address is not suppressed, the email is sent to the recipient’s mail server.
  3. Post-delivery event — If the email hard bounces, the recipient reports spam, or they unsubscribe, the address is automatically added to the suppression list. You receive a webhook notification for the event.
  4. Future sends blocked — Any subsequent sends targeting that address are rejected at the suppression check stage, preventing further damage to your sender reputation.

​
Why Suppressions Matter

Suppressions directly impact your ability to deliver email. Email providers evaluate your sender reputation based on measurable signals:
MetricDanger ThresholdConsequence
Bounce rate> 2%Providers may throttle or block your sending
Complaint rate> 0.1%Gmail and other providers move your emails to spam
Unsubscribe rate> 0.5%Signals low engagement, hurts inbox placement
Without suppressions, these rates climb quickly. A single batch sent to a stale list can push your bounce rate above safe thresholds, damaging your reputation for weeks.
Sending to addresses that have bounced or complained damages your reputation with email providers. High bounce rates or complaint rates can result in your emails being blocked or sent to spam. Suppressions prevent you from repeatedly hitting known-bad addresses.
Email providers track your sending patterns. A clean sending history with low bounces and complaints signals that you’re a legitimate sender, improving inbox placement for all your emails — not just the ones to clean addresses.
Every email you send counts against your plan quota. Suppressing invalid addresses prevents wasted sends and keeps your costs predictable.

​
Automatic Suppression

Lettr automatically suppresses addresses when certain events occur:
EventSuppression Behavior
Hard bounceAddress is permanently suppressed
Spam complaintAddress is permanently suppressed
List unsubscribeAddress is permanently suppressed
Link unsubscribeAddress is permanently suppressed
Soft bounces (temporary failures like mailbox full) do not result in immediate suppression. Delivery is retried automatically and the address is only suppressed after repeated failures.

​
Monitoring Suppressions

You can track suppression events using webhooks. When an address is suppressed due to a bounce, complaint, or unsubscribe, you receive a webhook event that you can use to update your own systems. Webhook payloads arrive as an array of events in SparkPost format. Each event is wrapped in an msys object containing the event category and data. See Handling Webhooks for full details on the payload structure.

​
Bounce Events

app.post('/webhooks/lettr', express.json(), async (req, res) => {
  res.sendStatus(200);

  for (const event of req.body) {
    const eventType = Object.keys(event.msys)[0];
    const data = event.msys[eventType];

    if (data.type === 'bounce' && parseInt(data.bounce_class) === 10) {
      // bounce_class 10 = Invalid Recipient (hard bounce)
      await db.subscribers.update({
        where: { email: data.rcpt_to },
        data: {
          status: 'invalid',
          bounceReason: data.raw_reason
        }
      });
    }
  }
});

​
Complaint Events

// Inside your event processing loop
if (data.type === 'spam_complaint') {
  // Mark as complained in your system
  await db.subscribers.update({
    where: { email: data.rcpt_to },
    data: {
      status: 'complained',
      canEmail: false
    }
  });

  // Alert your team about the complaint
  await alertTeam(`Spam complaint received from ${data.rcpt_to}`);
}

​
Unsubscribe Events

// Inside your event processing loop
if (data.type === 'list_unsubscribe' || data.type === 'link_unsubscribe') {
  // Update subscription status
  await db.subscribers.update({
    where: { email: data.rcpt_to },
    data: {
      status: 'unsubscribed',
      unsubscribedAt: new Date(),
      unsubscribeMethod: data.type // 'list_unsubscribe' or 'link_unsubscribe'
    }
  });
}

​
Best Practices

1

Handle Webhook Events

Set up webhook handlers for bounce, complaint, and unsubscribe events. Use these to keep your mailing lists clean.
2

Remove Invalid Addresses

When you receive a hard bounce, remove the address from your active mailing lists immediately.
3

Honor Unsubscribes

Process unsubscribe requests promptly. Never attempt to re-add someone who has unsubscribed.
4

Monitor Your Rates

Keep an eye on your bounce and complaint rates in the Lettr dashboard. High rates indicate list quality issues.

​
Learn More

Bounces

Understanding bounce types and handling strategies

Complaints & Unsubscribes

Handle spam complaints and opt-out requests

Webhook Events

Complete reference for all webhook event types

Handling Webhooks

Best practices for processing webhooks reliably