---
title: "Suppress an email address"
method: POST
path: "/suppressions"
tags: ["Suppressions"]
---

# Suppress an email address

`POST /suppressions`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/suppressions`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Adds a `manual` suppression so nothing is sent to the address. The address is trimmed and lowercased. When an active entry already covers the address, it is returned with status 200: its scope widens to `all` if you ask for `all`, a soft-bounce pause becomes a permanent manual entry, and a permanent entry is never shortened. When there is no active entry, or the previous one has expired, a new entry is stored and returned with status 201. Calling it twice with the same body has the same effect as calling it once.

## Headers

- `X-Shipmail-Organization` string

## Request body

- CreateSuppressionRequest
  - `email` string, email, required: The address to suppress. Trimmed and lowercased before it is stored.
  - `scope` 'all' | 'marketing': `all` blocks every send. `marketing` blocks newsletter sends only.

## Response `200`

An active entry already covered the address. Returns it, widened if requested.

- Suppression
  - `object` 'suppression', required
  - `email_address` string, email, required: The suppressed email address.
  - `reason` 'hard_bounce' | 'complaint' | 'manual' | 'soft_bounce', required: Why the address was suppressed. `soft_bounce`: at least 3 temporary bounces (mailbox full or a general temporary failure) in 14 days.
  - `scope` 'all' | 'marketing', required: Which sends the entry blocks. `all` blocks every send. `marketing` blocks newsletter sends only and is set by a complaint about a newsletter.
  - `expires_at` string, date-time, nullable, required: When the entry stops blocking sends, or null when it is permanent. A soft-bounce entry lasts 30 days; a second one for the same address is permanent.
  - `created_at` string, date-time, required: When the address was suppressed.

## Other responses

- `201`: Suppression created, or an expired entry replaced.
- `400`: Validation failed.
- `401`: Authentication failed.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/shipmail/apis/shipmail-api.md) · [All operations](https://skmtc.dev/shipmail/apis/shipmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmail/apis/shipmail-api/revisions/2c23e59d7e30?raw)