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

# POST /v1/suppression-list — Suppress Email Addresses

> POST /v1/suppression-list — Adds email addresses to your workspace suppression list. Suppressed addresses are skipped in all future campaigns.

The suppression list gives you a programmatic way to ensure that certain email addresses are never contacted through Leadterra, regardless of which campaign they appear in. This is useful for honoring unsubscribe requests received outside of Leadterra, removing known bad addresses from deliverability protection, or syncing opt-out data from a CRM or preference center. Once an address is suppressed, it is excluded from sending across your entire workspace — not just a single campaign.

## Endpoint

```bash theme={null}
POST /v1/suppression-list
```

## Authorization

All requests must include a valid API key in the `Authorization` header as a Bearer token.

```bash theme={null}
Authorization: Bearer sk_live_YOUR_KEY
```

## Request Body

<ParamField body="emails" type="array" required>
  An array of email address strings to add to the suppression list. You may submit up to 1,000 addresses per request. Addresses that are already suppressed are silently ignored — they will not be counted in the `suppressed` response value and will not cause an error.
</ParamField>

## Example Request

```bash theme={null}
curl -X POST https://app.leadterra.co/v1/suppression-list \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "unsubscribed@example.com",
      "bounced@example.com"
    ]
  }'
```

## Response Fields

<ResponseField name="suppressed" type="integer">
  The number of email addresses that were newly added to the suppression list in this request. Addresses that were already suppressed prior to this request are not counted.
</ResponseField>

## Example Response

```json theme={null}
{
  "suppressed": 2
}
```

<Warning>
  **Suppression is workspace-wide and cannot be undone via the API.** Once an address is added to your suppression list it applies to all current and future campaigns across your entire workspace. There is no API endpoint to remove an address from the suppression list — removals must be performed manually through the Leadterra dashboard under **Settings → Suppression List**.
</Warning>

## Error Codes

| Code  | Meaning                                                                                                                                                        |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Bad Request — the request body is malformed, the `emails` field is missing, or the array is empty.                                                             |
| `401` | Unauthorized — your API key is missing, invalid, or revoked.                                                                                                   |
| `404` | Not Found — the requested resource could not be located.                                                                                                       |
| `422` | Unprocessable Entity — one or more email addresses failed format validation. The response body will include an `errors` array identifying the invalid entries. |