> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Protect your sender reputation by managing suppressed addresses in Lettr that have bounced, complained, or unsubscribed from your emails.

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:

| Reason             | Description                                         | How It's Added               |
| ------------------ | --------------------------------------------------- | ---------------------------- |
| **Hard bounce**    | Address doesn't exist or is permanently unreachable | Automatically on bounce      |
| **Spam complaint** | Recipient marked your email as spam                 | Automatically on complaint   |
| **Unsubscribe**    | Recipient opted out via List-Unsubscribe            | Automatically 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:

| Metric               | Danger Threshold | Consequence                                        |
| -------------------- | ---------------- | -------------------------------------------------- |
| **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.

<AccordionGroup>
  <Accordion title="Protect Sender Reputation">
    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.
  </Accordion>

  <Accordion title="Improve Deliverability">
    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.
  </Accordion>

  <Accordion title="Legal Compliance">
    Laws like CAN-SPAM and GDPR require you to honor unsubscribe requests. Suppression lists ensure you don't accidentally email people who have opted out, which can result in fines and legal liability.
  </Accordion>

  <Accordion title="Reduce Costs">
    Every email you send counts against your plan quota. Suppressing invalid addresses prevents wasted sends and keeps your costs predictable.
  </Accordion>
</AccordionGroup>

## Automatic Suppression

Lettr automatically suppresses addresses when certain events occur:

| Event                | Suppression Behavior              |
| -------------------- | --------------------------------- |
| **Hard bounce**      | Address is permanently suppressed |
| **Spam complaint**   | Address is permanently suppressed |
| **List unsubscribe** | Address is permanently suppressed |
| **Link unsubscribe** | Address is permanently suppressed |

<Note>
  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.
</Note>

## 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](/learn/webhooks/handling) for full details on the payload structure.

### Bounce Events

```javascript theme={null}
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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

<Steps>
  <Step title="Handle Webhook Events">
    Set up webhook handlers for bounce, complaint, and unsubscribe events. Use these to keep your mailing lists clean.
  </Step>

  <Step title="Remove Invalid Addresses">
    When you receive a hard bounce, remove the address from your active mailing lists immediately.
  </Step>

  <Step title="Honor Unsubscribes">
    Process unsubscribe requests promptly. Never attempt to re-add someone who has unsubscribed.
  </Step>

  <Step title="Monitor Your Rates">
    Keep an eye on your bounce and complaint rates in the Lettr dashboard. High rates indicate list quality issues.
  </Step>
</Steps>

## Learn More

<CardGroup cols={2}>
  <Card title="Bounces" icon="arrow-rotate-left" href="/learn/suppressions/bounces">
    Understanding bounce types and handling strategies
  </Card>

  <Card title="Complaints & Unsubscribes" icon="ban" href="/learn/suppressions/complaints-unsubscribes">
    Handle spam complaints and opt-out requests
  </Card>

  <Card title="Webhook Events" icon="bell" href="/learn/webhooks/event-types">
    Complete reference for all webhook event types
  </Card>

  <Card title="Handling Webhooks" icon="code" href="/learn/webhooks/handling">
    Best practices for processing webhooks reliably
  </Card>
</CardGroup>