# Suppressions

# Suppressions

Suppressions prevent Lettermint from sending to recipients that should not receive more email. They protect deliverability, honor recipient choices, and help enforce compliance decisions.

## Reasons

| Reason | API value | Created by |
|--------|-----------|------------|
| Hard bounce | `hard_bounce` | Lettermint after permanent delivery failure |
| Spam complaint | `spam_complaint` | Lettermint after a recipient reports spam |
| Unsubscribe | `unsubscribe` | Hosted unsubscribe and unsubscribe workflows |
| Manual | `manual` | Dashboard or Team API |

:::info
The suppression reason is `unsubscribe`. The webhook event for a recipient unsubscribe is `message.unsubscribed`.
:::

## Scopes

| Scope | Applies to | Required ID |
|-------|------------|-------------|
| Team | All projects and routes in the team | None |
| Project | All routes in one project | `project_id` |
| Route | One route | `route_id` |

Higher-level suppressions take precedence. A team-level suppression blocks sends across all projects and routes.

<Frame>
  {/* Screenshot placeholder: /docs/images/suppressions/suppression-list.png */}
  Suppressions table with reason, scope, route, project, and created date.
</Frame>

## Add suppressions

You can add one address or up to 1000 addresses in one Team API request.

<CodeTabs syncKey="lettermint-language">

```bash title="cURL"
curl -X POST "https://api.lettermint.co/v1/suppressions" \
  -H "Authorization: Bearer $LETTERMINT_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["customer@example.com"],
    "reason": "manual",
    "scope": "project",
    "project_id": "project-id"
  }'
```

```typescript title="Node.js"
await api.suppressions.create({
  emails: ["customer@example.com"],
  reason: "manual",
  scope: "project",
  project_id: "project-id",
});
```

```php title="PHP"
$api->suppressions->create([
    'emails' => ['customer@example.com'],
    'reason' => 'manual',
    'scope' => 'project',
    'project_id' => 'project-id',
]);
```

</CodeTabs>

<Frame>
  {/* Screenshot placeholder: /docs/images/suppressions/add-suppression-dialog.png */}
  Add suppression dialog with email, reason, and scope.
</Frame>

<OpenPlaygroundButton
  server="https://api.lettermint.co/v1"
  url="/suppressions"
  method="POST"
  headers={[
    { name: "Authorization", defaultValue: "Bearer lm_team_your_token" },
    { name: "Content-Type", defaultValue: "application/json" },
  ]}
  body={JSON.stringify({
    email: "customer@example.com",
    reason: "manual",
    scope: "team",
  })}
>
  Add a suppression
</OpenPlaygroundButton>

## Remove suppressions

Manual, hard bounce, and unsubscribe suppressions can be removed when appropriate. Spam complaint suppressions cannot be removed through normal self-service; contact support if you believe one needs review.

## Next steps

- [Email activity](/platform/emails/activity) - Inspect suppressed message events
- [Routes](/platform/projects-and-routes/routes) - Understand route-level lists
- [Team API reference](/api-reference/team) - Review suppression endpoints