Suppressions

Read and manage the addresses Emailit will not send to.

Base URLhttps://api.emailit.com/v2Authentication Errors Rate limits

POST/suppressions
GET/suppressions/{id}
POST/suppressions/{id}
GET/suppressions
DEL/suppressions/{id}

Create a suppression

Adds an address to your workspace’s suppression list. API and SMTP emails to an address with a recipient suppression get the status suppressed instead of being sent, and campaigns skip suppressed addresses. Requires an API key with full scope.

POST/suppressions

Request body

emailstringRequired

Address to suppress. Emailit stores it in lowercase.

typestring

Suppression type. Default recipient. Emailit uses recipient, bounce, complaint and unsubscribe.

Only recipient suppressions stop emails sent through the API and SMTP. Campaigns skip every address with an active suppression of any type. An address can have one suppression per type.

reasonstring

Free-text note, for example manual or Asked to stop receiving invoices.

keep_untilstring | number | null

When the suppression expires. Accepts an ISO 8601 timestamp (2026-12-31T00:00:00Z), a Unix timestamp in seconds (1798675200), or natural language such as in 30 days or tomorrow at 9am. Omit it or send null for a permanent suppression.

After this time the suppression stops blocking sends. It stays in the list until you delete it.

Returns

Returns 201 Created with the suppression object. Emailit also sends a suppression.created webhook event.

Status	When
`400`	`email` isn’t a valid address or `keep_until` can’t be parsed (the body has an `error` string), or `email` is missing (standard validation error).
`409`	The address already has a suppression of this type. The body includes the `existing` suppression.

POST/suppressions

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const suppression = await emailit.suppressions.create({
    email: 'ada@example.com',
    reason: 'manual'
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

suppression = client.suppressions.create({
    "email": "ada@example.com",
    "reason": "manual"
})

PHP

$emailit = Emailit::client('your_api_key');

$suppression = $emailit->suppressions()->create([
    'email' => 'ada@example.com',
    'reason' => 'manual'
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

suppression = client.suppressions.create(
    email: "ada@example.com",
    reason: "manual"
)

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

suppression, err := client.Suppressions.Create(&emailit.CreateSuppressionRequest{
    Email: "ada@example.com",
    Reason: "manual",
})

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let suppression = emailit.suppressions.create(
    emailit::types::CreateSuppressionParams::new("ada@example.com")
        .with_reason("manual")
).await?;

Java

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject suppression = emailit.suppressions().create(
    SuppressionCreateParams.builder()
        .setEmail("ada@example.com")
        .setReason("manual")
        .build()
);

using Emailit;
var emailit = new EmailitClient("your_api_key");

var suppression = emailit.Suppressions.Create(new SuppressionCreateOptions {
    Email = "ada@example.com",
    Reason = "manual"
});

PHP

use Emailit\Laravel\Facades\Emailit;

$suppression = Emailit::suppressions()->create([
    'email' => 'ada@example.com',
    'reason' => 'manual'
]);

Terminal

curl -X POST https://api.emailit.com/v2/suppressions \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "reason": "manual"
  }'

JSON

{
  "object": "suppression",
  "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
  "type": "recipient",
  "email": "ada@example.com",
  "reason": "manual",
  "created_at": "2026-10-01T09:30:12.481000+00:00",
  "keep_until": null
}

JSON

{
  "error": "Invalid keep_until format. Accepts ISO 8601, Unix timestamp, or natural language like \"tomorrow at 9am\"."
}

JSON

{
  "error": "Suppression already exists for this email and type",
  "existing": {
    "object": "suppression",
    "id": "sup_2xKz0Pq5Rm8Nw2Tb7YdLc4HsE1a",
    "type": "recipient",
    "email": "ada@example.com",
    "reason": "too many bounces",
    "created_at": "2026-09-12T16:04:51.207000+00:00",
    "keep_until": null
  }
}

Retrieve a suppression

Returns one suppression, looked up by ID or by email address. Requires an API key with full scope.

GET/suppressions/:id

Path parameters

idstringRequired

Suppression ID (sup_…) or the suppressed address. URL-encode the address, for example ada%40example.com.

An address can have one suppression per type. When you look up by address, Emailit returns one of them; use the ID to target a specific type.

Returns

Returns 200 OK with the suppression object. A suppression whose keep_until is in the past no longer blocks sending.

Returns 400 if id is neither a sup_ ID nor a valid email address, and 404 if no suppression matches.

GET/suppressions/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const suppression = await emailit.suppressions.get('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

suppression = client.suppressions.get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")

PHP

$emailit = Emailit::client('your_api_key');

$suppression = $emailit->suppressions()->get('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

suppression = client.suppressions.get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

suppression, err := client.Suppressions.Get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let suppression = emailit.suppressions.get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e").await?;

Java

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject suppression = emailit.suppressions().get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e");

using Emailit;
var emailit = new EmailitClient("your_api_key");

var suppression = emailit.Suppressions.Get("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e");

PHP

use Emailit\Laravel\Facades\Emailit;

$suppression = Emailit::suppressions()->get('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');

Terminal

curl https://api.emailit.com/v2/suppressions/sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e \
  -H "Authorization: Bearer your_api_key"

JSON

{
  "object": "suppression",
  "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
  "type": "recipient",
  "email": "ada@example.com",
  "reason": "too many bounces",
  "created_at": "2026-10-01T09:30:12.481000+00:00",
  "keep_until": null
}

JSON

{
  "error": "Invalid identifier. Must be a suppression ID (sup_xxx) or valid email address."
}

JSON

{
  "error": "Suppression not found"
}

Update a suppression

Updates a suppression. Send only the fields you want to change; at least one is required. Requires an API key with full scope.

POST/suppressions/:id

Path parameters

idstringRequired

Suppression ID (sup_…) or the suppressed address, URL-encoded (ada%40example.com). When an address has suppressions of several types, use the ID.

Request body

emailstring

New address. Stored in lowercase.

typestring

New type: recipient, bounce, complaint or unsubscribe. Only recipient suppressions stop API and SMTP sends.

reasonstring

New free-text reason.

keep_untilstring | number | null

New expiry, in the same formats as on create: ISO 8601, a Unix timestamp in seconds, or natural language like in 30 days. Send null to make the suppression permanent.

Returns

Returns 200 OK with the updated suppression. Emailit also sends a suppression.updated webhook event.

Status	When
`400`	The body has none of the fields above, `email` is invalid, or `keep_until` can’t be parsed.
`404`	No suppression matches `id`.
`409`	Another suppression already exists for the new address and type.

POST/suppressions/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const suppression = await emailit.suppressions.update('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e', {
    reason: 'Asked to pause invoices until January'
});

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

suppression = client.suppressions.update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e", {
    "reason": "Asked to pause invoices until January"
})

PHP

$emailit = Emailit::client('your_api_key');

$suppression = $emailit->suppressions()->update('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e', [
    'reason' => 'Asked to pause invoices until January'
]);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

suppression = client.suppressions.update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e", reason: "Asked to pause invoices until January")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

suppression, err := client.Suppressions.Update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e", &emailit.UpdateSuppressionRequest{
    Reason: "Asked to pause invoices until January",
})

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let suppression = emailit.suppressions.update(
    "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
    emailit::types::UpdateSuppressionParams {
        reason: Some("Asked to pause invoices until January".into()),
        ..Default::default()
    }
).await?;

Java

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject suppression = emailit.suppressions().update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
    SuppressionUpdateParams.builder()
        .setReason("Asked to pause invoices until January")
        .build()
);

using Emailit;
var emailit = new EmailitClient("your_api_key");

var suppression = emailit.Suppressions.Update("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
    new SuppressionUpdateOptions { Reason = "Asked to pause invoices until January" });

PHP

use Emailit\Laravel\Facades\Emailit;

$suppression = Emailit::suppressions()->update('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e', [
    'reason' => 'Asked to pause invoices until January'
]);

Terminal

curl -X POST https://api.emailit.com/v2/suppressions/sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Asked to pause invoices until January"}'

JSON

{
  "object": "suppression",
  "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
  "type": "recipient",
  "email": "ada@example.com",
  "reason": "Asked to pause invoices until January",
  "created_at": "2026-10-01T09:30:12.481000+00:00",
  "keep_until": "2027-01-01T00:00:00.000000+00:00"
}

JSON

{
  "error": "No valid fields provided for update. Provide at least one of: email, type, reason, keep_until"
}

JSON

{
  "error": "Suppression not found"
}

JSON

{
  "error": "Another suppression already exists for this email and type combination"
}

List suppressions

Returns the suppressions in your workspace, newest first. The list includes the suppressions Emailit adds automatically after bounces and complaints, and expired suppressions whose keep_until has passed. Requires an API key with full scope.

GET/suppressions

Query parameters

pageinteger

Page number, starting at 1. Default 1.

limitinteger

Suppressions per page, from 1 to 100. Default 10.

searchstring

Case-insensitive match on the address or the reason. q works as an alias.

matchstring

all (default) requires every key.condition filter to match. or matches any of them. See Filtering.

sortstring

Sort key: email, reason, type or created_at (default).

orderstring

Sort direction: asc or desc (default).

Filters

List filters are one layer of key.condition=value query parameters. See Filtering for match, order, direction and the condition list per type.

Filter keys

Key	Type	Conditions
`email`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`reason`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`type`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty
`keep_until`	date	exact, before, after, empty, not_empty

Sort keys

This endpoint sorts with sort set to one of these keys and order set to asc or desc (order=<key> returns 400 here): email, reason, type, created_at, keep_until

On this endpoint, order only accepts asc or desc. Pass the sort key in sort, for example sort=email&order=asc.

Returns

Returns 200 OK with the suppressions in data, plus next_page_url and previous_page_url (null when there is no next or previous page). The page URLs keep your search, filters and sort.

GET/suppressions

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const suppressions = await emailit.suppressions.list();

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

suppressions = client.suppressions.list()

PHP

$emailit = Emailit::client('your_api_key');

$suppressions = $emailit->suppressions()->list();

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

suppressions = client.suppressions.list

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

suppressions, err := client.Suppressions.List(nil)

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let suppressions = emailit.suppressions.list(None).await?;

Java

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject suppressions = emailit.suppressions().list();

using Emailit;
var emailit = new EmailitClient("your_api_key");

var suppressions = emailit.Suppressions.List();

PHP

use Emailit\Laravel\Facades\Emailit;

$suppressions = Emailit::suppressions()->list();

Terminal

curl https://api.emailit.com/v2/suppressions \
  -H "Authorization: Bearer your_api_key"

JSON

{
  "data": [
    {
      "object": "suppression",
      "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
      "type": "recipient",
      "email": "ada@example.com",
      "reason": "too many bounces",
      "created_at": "2026-10-01T09:30:12.481000+00:00",
      "keep_until": null
    },
    {
      "object": "suppression",
      "id": "sup_2xKz0Pq5Rm8Nw2Tb7YdLc4HsE1a",
      "type": "complaint",
      "email": "grace@example.com",
      "reason": "complaint",
      "created_at": "2026-09-28T13:17:40.912000+00:00",
      "keep_until": null
    }
  ],
  "next_page_url": "/v2/suppressions?limit=10&page=2",
  "previous_page_url": null
}

JSON

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Delete a suppression

Deletes a suppression so the address can receive email again. Requires an API key with full scope.

DELETE/suppressions/:id

Path parameters

idstringRequired

Suppression ID (sup_…) or the suppressed address, URL-encoded (ada%40example.com).

A request by address deletes one suppression. If the address has suppressions of several types, delete each by ID, or repeat the request until it returns 404.

Returns

Returns 200 OK with the id and email of the deleted suppression and deleted: true. Emailit also sends a suppression.deleted webhook event.

Returns 400 if id is neither a sup_ ID nor a valid email address, and 404 if no suppression matches.

DELETE/suppressions/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

await emailit.suppressions.delete('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

client.suppressions.delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")

PHP

$emailit = Emailit::client('your_api_key');

$emailit->suppressions()->delete('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

client.suppressions.delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

err := client.Suppressions.Delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

emailit.suppressions.delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e").await?;

Java

import com.emailit.*;
import com.emailit.params.*;
EmailitClient emailit = new EmailitClient("your_api_key");

emailit.suppressions().delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e");

using Emailit;
var emailit = new EmailitClient("your_api_key");

emailit.Suppressions.Delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e");

PHP

use Emailit\Laravel\Facades\Emailit;

Emailit::suppressions()->delete('sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e');

Terminal

curl -X DELETE https://api.emailit.com/v2/suppressions/sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e \
  -H "Authorization: Bearer your_api_key"

JSON

{
  "object": "suppression",
  "id": "sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e",
  "email": "ada@example.com",
  "deleted": true
}

JSON

{
  "error": "Invalid identifier. Must be a suppression ID (sup_xxx) or valid email address."
}

JSON

{
  "error": "Suppression not found"
}