---
title: "Add an allowlist entry"
method: POST
path: "/v1/suppression/allow"
tags: ["Suppression"]
---

# Add an allowlist entry

`POST /v1/suppression/allow`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/suppression/allow`
- Auth: HTTP bearer

**Requires scope:** `manage`. Attests that a recipient consents, overriding non-hard-bounce suppression for that address.

## Request body

- AllowSuppressionRequest
  - `address` string, email, required: The recipient to send to again despite a complaint or unsubscribe; a hard bounce is not lifted. Matched in lowercase, without any `+tag` and, for gmail.com and googlemail.com, without dots before the `@`, so one entry covers each such spelling.
  - `attestation` string, required: Your statement that the recipient agreed to receive your mail, 20 to 2,000 characters. It is stored with the entry and returned with it.

## Response `201`

The created allowlist entry.

- SuppressionEntry
  - `id` string, required: Allowlist entry id (`sup_…`); revoke it with `DELETE /v1/suppression/allow/{id}`.
  - `address` string, email, required: The address the entry covers. The create response echoes it as sent; the list shows it as matched: lowercase, without a `+tag`, and for Gmail without dots before the `@`.
  - `attestation` string, required: Your statement that the recipient agreed to receive your mail, as given when the entry was added.
  - `revoked_at` string, date-time: When the entry was revoked. Absent while it is active; a revoked entry stays in the list but lifts nothing.
  - `created_at` string, date-time, required: When the entry was added (UTC).

## Other responses

- `400`: Invalid request — malformed JSON or a field failed validation. Also `feature_not_enabled` when this server has a feature switched off (custom domains before they are available).
- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)