# Add addresses

> Requires X-Api-Key. Not project-scoped. The list applies to a whole workspace, not a single project. The workspace is the one named by the X-Workspace-Id…

Source: https://warmerly.com/docs/suppression/add-addresses

```text
POST /suppression
```

Requires `X-Api-Key`. **Not** project-scoped. The list applies to a whole workspace, not a single project. The workspace is the one named by the [`X-Workspace-Id`](https://warmerly.com/docs/authentication#required-headers) header (you must be a member of it), otherwise your own personal workspace.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `emails` | string (1-1,000,000 chars) | Yes | A blob of addresses separated by commas, semicolons, spaces, tabs, or newlines. Tolerates `Name <a@b.com>` formatting and a leading `email`/`email_address` CSV header, so you can paste a raw CSV column unedited. |

Up to **5,000** addresses per request. Every address added this way is recorded with `reason: "manual"`; the `unsubscribed` and `bounced` reasons are set only by Warmerly itself (the unsubscribe link and the bounce classifier), so a hand-typed address is never attributed to either.

```bash
curl -X POST https://app.warmerly.com/api/v1/suppression \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "emails": "jane@example.com, john@example.com" }'
```

`201 Created`:

```json
{ "added": 2, "alreadyPresent": 0, "invalid": [] }
```

`added` is new rows inserted; `alreadyPresent` is addresses already on the workspace's list (adding one twice is a no-op, and an address repeated inside one request is counted once); `invalid` lists tokens that looked like an email attempt (contained `@`) but failed validation. Addresses are lowercased.

Errors:

| Status | `message` | When |
| --- | --- | --- |
| `400` | `invalid_body` | `emails` missing, empty, or over 1,000,000 characters. |
| `400` | `no_valid_emails` | Nothing in `emails` parsed as a valid address. `details.invalid` samples up to 20 of the rejected tokens. |
| `400` | `too_many_emails` | More than 5,000 addresses parsed. `details` carries `{ max, received }`. |

Every add is recorded in the workspace audit log as `suppression.added` (removals, when staff perform them, as `suppression.removed`).

## More from Suppression

- [How suppression works with campaigns](https://warmerly.com/docs/suppression/how-suppression-works-with-campaigns): Suppression is workspace-wide, not per campaign or per project. An opt-out holds across every campaign and…
- [The list is write-only](https://warmerly.com/docs/suppression/the-list-is-write-only): POST /suppression is the only customer-callable endpoint on this resource. Adding an address works with your…
- [Other ways to add addresses](https://warmerly.com/docs/suppression/other-ways-to-add-addresses): Other ways to add addresses in the Warmerly Suppression API reference.