List Suppressions

Retrieve a paginated list of all suppressions in your Emailit workspace.

GET/suppressions

Query Parameters

limitinteger

Items per page (1-100). Default: 10.

pageinteger

Page number. Default: 1.

GET /suppressions

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

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

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

suppressions = client.suppressions.list()

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

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

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)

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

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

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();

use Emailit\Laravel\Facades\Emailit;

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

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

{
  "data": [
    {
      "object": "suppression",
      "id": "sup_47TaFwzJx6mD7NeJYvLjFxVwbgT",
      "email": "bounced@example.com",
      "type": "bounce",
      "reason": "Hard bounce - mailbox does not exist",
      "timestamp": "2025-12-24T10:30:00.000000Z",
      "keep_until": null
    }
  ],
  "next_page_url": "/v2/suppressions?page=2&limit=10",
  "previous_page_url": null
}

{
  "message": "Unauthorized"
}

Get Suppression

Retrieve a single suppression by ID or email address.

GET/suppressions/:id

Path Parameters

idstringRequired

Suppression ID (sup_xxx) or email address. When using an email address, URL-encode the @ symbol (e.g., user%40example.com).

GET /suppressions/{id}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

use Emailit\Laravel\Facades\Emailit;

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

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

{
  "object": "suppression",
  "id": "sup_47TaFwzJx6mD7NeJYvLjFxVwbgT",
  "email": "bounced@example.com",
  "type": "bounce",
  "reason": "Hard bounce - mailbox does not exist",
  "timestamp": "2025-12-24T10:30:00.000000Z",
  "keep_until": null
}

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

{
  "error": "Suppression not found"
}

Lookup by Email

You can also look up a suppression by email address instead of ID. When using email addresses in URLs, the address must be URL-encoded (e.g., bounced%40example.com instead of bounced@example.com).

Create Suppression

Add an email address to the suppression list to prevent sending emails to that address.

POST/suppressions

Request Body

emailstringRequired

Email address to suppress. Will be stored in lowercase.

typestring

Suppression type (e.g., recipient, bounce, complaint, unsubscribe). Default: recipient.

reasonstring

Human-readable reason for the suppression.

keep_untilstring

Expiration timestamp in ISO 8601 format. Set to null for permanent suppression.

POST /suppressions

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

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

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

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

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

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

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

suppression = client.suppressions.create(
    email: "user@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: "user@example.com",
    Reason: "manual",
})

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

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

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

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

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

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

use Emailit\Laravel\Facades\Emailit;

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

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

{
  "object": "suppression",
  "id": "sup_47TaFwzJx6mD7NeJYvLjFxVwbgT",
  "email": "unsubscribed@example.com",
  "type": "unsubscribe",
  "reason": "User requested unsubscription",
  "timestamp": "2025-12-24T10:30:00.000000Z",
  "keep_until": null
}

{
  "error": "Invalid email format"
}

{
  "error": "Missing required field: email"
}

{
  "error": "Suppression already exists for this email and type",
  "existing": {
    "object": "suppression",
    "id": "sup_existingOid123456789",
    "email": "unsubscribed@example.com",
    "type": "unsubscribe",
    "reason": "Previous reason",
    "timestamp": "2025-12-20T08:00:00.000000Z",
    "keep_until": null
  }
}

Temporary Suppressions

Use keep_until to create a temporary suppression that expires automatically. The format is the same as scheduled_at for emails: accepts ISO 8601, Unix timestamp, or natural language like “tomorrow at 9am”.

After the keep_until timestamp passes, the suppression is automatically removed and emails can be sent to that address again.

Update Suppression

Update an existing suppression. The :id parameter accepts either a suppression ID or email address.

POST/suppressions/:id

Path Parameters

idstringRequired

Suppression ID (sup_xxx) or email address. When using an email address, URL-encode the @ symbol.

Request Body (all optional)

emailstring

New email address for the suppression.

typestring

New suppression type.

reasonstring

New reason for the suppression.

keep_untilstring | null

New expiration timestamp (ISO 8601) or null for permanent suppression.

PATCH /suppressions/{id}

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

const suppression = await emailit.suppressions.update('sup_123', {
    reason: 'bounce'
});

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

suppression = client.suppressions.update("sup_123", {
    "reason": "bounce"
})

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

$suppression = $emailit->suppressions()->update('sup_123', [
    'reason' => 'bounce'
]);

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

suppression = client.suppressions.update("sup_123", reason: "bounce")

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

suppression, err := client.Suppressions.Update("sup_123", &emailit.UpdateSuppressionRequest{
    Reason: "bounce",
})

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

let suppression = emailit.suppressions.update(
    "sup_123",
    emailit::types::UpdateSuppressionParams {
        reason: Some("bounce".into()),
        ..Default::default()
    }
).await?;

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

EmailitObject suppression = emailit.suppressions().update("sup_123",
    SuppressionUpdateParams.builder()
        .setReason("bounce")
        .build()
);

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

var suppression = emailit.Suppressions.Update("sup_123",
    new SuppressionUpdateOptions { Reason = "bounce" });

use Emailit\Laravel\Facades\Emailit;

$suppression = Emailit::suppressions()->update('sup_123', [
    'reason' => 'bounce'
]);

curl -X PATCH https://api.emailit.com/v2/suppressions/sup_123 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "bounce"}'

{
  "object": "suppression",
  "id": "sup_47TaFwzJx6mD7NeJYvLjFxVwbgT",
  "email": "bounced@example.com",
  "type": "bounce",
  "reason": "Updated reason for suppression",
  "timestamp": "2025-12-24T10:30:00.000000Z",
  "keep_until": "2026-01-01T00:00:00.000000Z"
}

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

{
  "error": "Suppression not found"
}

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

Important Notes

At least one field must be provided in the request body.
If you change the email or type to a combination that already exists, you’ll receive a 409 conflict error.
You can look up the suppression by email address instead of ID by URL-encoding the @ symbol (e.g., bounced%40example.com).

Delete Suppression

Remove a suppression to allow sending emails to that address again.

DELETE/suppressions/:id

Path Parameters

idstringRequired

Suppression ID (sup_xxx) or email address. When using an email address, URL-encode the @ symbol (e.g., user%40example.com).

DELETE /suppressions/{id}

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

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

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

client.suppressions.delete("sup_123")

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

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

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

client.suppressions.delete("sup_123")

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

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

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

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

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

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

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

emailit.Suppressions.Delete("sup_123");

use Emailit\Laravel\Facades\Emailit;

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

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

{
  "object": "suppression",
  "id": "sup_47TaFwzJx6mD7NeJYvLjFxVwbgT",
  "email": "bounced@example.com",
  "deleted": true
}

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

{
  "error": "Suppression not found"
}

Delete by Email

You can also delete a suppression by email address instead of ID. When using email addresses in URLs, the address must be URL-encoded (e.g., bounced%40example.com instead of bounced@example.com).