Sperrungen

Die Adressen lesen und verwalten, an die Emailit nicht sendet.

Basis-URLhttps://api.emailit.com/v2Authentifizierung Fehler Rate Limits

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

Sperrung erstellen

Setzt eine Adresse auf die Sperrliste Ihres Workspace. E-Mails per API und SMTP an eine Adresse mit einer Sperrung vom Typ recipient erhalten den Status suppressed, statt gesendet zu werden, und Kampagnen überspringen gesperrte Adressen. Erfordert einen API-Schlüssel mit dem Scope full.

POST/suppressions

Anfrage-Body

emailstringErforderlich

Die zu sperrende Adresse. Emailit speichert sie in Kleinbuchstaben.

typestring

Sperrtyp. Standardwert: recipient. Emailit verwendet recipient, bounce, complaint und unsubscribe.

Nur Sperrungen vom Typ recipient stoppen E-Mails, die per API und SMTP gesendet werden. Kampagnen überspringen jede Adresse mit einer aktiven Sperrung beliebigen Typs. Eine Adresse kann eine Sperrung pro Typ haben.

reasonstring

Notiz als Freitext, zum Beispiel manual oder Asked to stop receiving invoices.

keep_untilstring | number | null

Wann die Sperrung abläuft. Akzeptiert einen Zeitstempel im Format ISO 8601 (2026-12-31T00:00:00Z), einen Unix-Zeitstempel in Sekunden (1798675200) oder natürliche Sprache wie in 30 days oder tomorrow at 9am. Lassen Sie das Feld weg oder senden Sie null für eine dauerhafte Sperrung.

Nach diesem Zeitpunkt blockiert die Sperrung keine Sendungen mehr. Sie bleibt in der Liste, bis Sie sie löschen.

Rückgabe

Gibt 201 Created mit dem Sperrungs-Objekt zurück. Emailit sendet außerdem das Webhook-Event suppression.created.

Status	Wann
`400`	`email` ist keine gültige Adresse oder `keep_until` lässt sich nicht parsen (der Body enthält einen String `error`), oder `email` fehlt (Standard-Validierungsfehler).
`409`	Die Adresse hat bereits eine Sperrung dieses Typs. Der Body enthält die vorhandene Sperrung in `existing`.

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
  }
}

Sperrung abrufen

Gibt eine Sperrung zurück, gesucht per ID oder E-Mail-Adresse. Erfordert einen API-Schlüssel mit dem Scope full.

GET/suppressions/:id

Pfadparameter

idstringErforderlich

ID der Sperrung (sup_…) oder die gesperrte Adresse. Kodieren Sie die Adresse für die URL, zum Beispiel ada%40example.com.

Eine Adresse kann eine Sperrung pro Typ haben. Bei einer Suche per Adresse gibt Emailit eine davon zurück; um einen bestimmten Typ abzurufen, verwenden Sie die ID.

Rückgabe

Gibt 200 OK mit dem Sperrungs-Objekt zurück. Eine Sperrung, deren keep_until in der Vergangenheit liegt, blockiert den Versand nicht mehr.

Gibt 400 zurück, wenn id weder eine sup_-ID noch eine gültige E-Mail-Adresse ist, und 404, wenn keine Sperrung passt.

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"
}

Sperrung aktualisieren

Aktualisiert eine Sperrung. Senden Sie nur die Felder, die Sie ändern möchten; mindestens eines ist erforderlich. Erfordert einen API-Schlüssel mit dem Scope full.

POST/suppressions/:id

Pfadparameter

idstringErforderlich

ID der Sperrung (sup_…) oder die gesperrte Adresse, URL-kodiert (ada%40example.com). Hat eine Adresse Sperrungen mehrerer Typen, verwenden Sie die ID.

Anfrage-Body

emailstring

Neue Adresse. Wird in Kleinbuchstaben gespeichert.

typestring

Neuer Typ: recipient, bounce, complaint oder unsubscribe. Nur Sperrungen vom Typ recipient stoppen Sendungen per API und SMTP.

reasonstring

Neuer Grund als Freitext.

keep_untilstring | number | null

Neuer Ablaufzeitpunkt, in denselben Formaten wie beim Erstellen: ISO 8601, ein Unix-Zeitstempel in Sekunden oder natürliche Sprache wie in 30 days. Senden Sie null, um die Sperrung dauerhaft zu machen.

Rückgabe

Gibt 200 OK mit der aktualisierten Sperrung zurück. Emailit sendet außerdem das Webhook-Event suppression.updated.

Status	Wann
`400`	Der Body enthält keines der obigen Felder, `email` ist ungültig oder `keep_until` lässt sich nicht parsen.
`404`	Keine Sperrung passt zu `id`.
`409`	Für die neue Adresse und den neuen Typ existiert bereits eine andere Sperrung.

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"
}

Sperrungen auflisten

Gibt die Sperrungen in Ihrem Workspace zurück, die neuesten zuerst. Die Liste enthält auch die Sperrungen, die Emailit nach Bounces und Beschwerden automatisch hinzufügt, sowie abgelaufene Sperrungen, deren keep_until überschritten ist. Erfordert einen API-Schlüssel mit dem Scope full.

GET/suppressions

Query-Parameter

pageinteger

Seitennummer, beginnend bei 1. Standardwert: 1.

limitinteger

Sperrungen pro Seite, von 1 bis 100. Standardwert: 10.

searchstring

Abgleich mit Adresse oder Grund, ohne Beachtung der Groß-/Kleinschreibung. q funktioniert als Alias.

matchstring

all (Standardwert) verlangt, dass jeder Filter key.condition zutrifft. Bei or genügt einer davon. Siehe Filtern und Sortieren.

sortstring

Sortierschlüssel: email, reason, type oder created_at (Standardwert).

orderstring

Sortierrichtung: asc oder desc (Standardwert).

Filter

Listenfilter sind Query-Parameter der Form key.condition=value auf einer einzigen Ebene. match, order, direction und die Bedingungen pro Typ finden Sie unter Filtern und Sortieren.

Filterschlüssel

Schlüssel	Typ	Bedingungen
`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

Sortierschlüssel

Dieser Endpunkt sortiert mit sort, gesetzt auf einen dieser Schlüssel, und order, gesetzt auf asc oder desc (order=<key> gibt hier 400 zurück): email, reason, type, created_at, keep_until

Bei diesem Endpunkt akzeptiert order nur asc oder desc. Übergeben Sie den Sortierschlüssel in sort, zum Beispiel sort=email&order=asc.

Rückgabe

Gibt 200 OK mit den Sperrungen in data zurück, dazu next_page_url und previous_page_url (null, wenn es keine nächste bzw. vorherige Seite gibt). Die Seiten-URLs übernehmen Ihre Suche, Filter und Sortierung.

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"
}

Sperrung löschen

Löscht eine Sperrung, damit die Adresse wieder E-Mails empfangen kann. Erfordert einen API-Schlüssel mit dem Scope full.

DELETE/suppressions/:id

Pfadparameter

idstringErforderlich

ID der Sperrung (sup_…) oder die gesperrte Adresse, URL-kodiert (ada%40example.com).

Eine Anfrage per Adresse löscht eine Sperrung. Hat die Adresse Sperrungen mehrerer Typen, löschen Sie jede per ID oder wiederholen Sie die Anfrage, bis sie 404 zurückgibt.

Rückgabe

Gibt 200 OK mit id und email der gelöschten Sperrung sowie deleted: true zurück. Emailit sendet außerdem das Webhook-Event suppression.deleted.

Gibt 400 zurück, wenn id weder eine sup_-ID noch eine gültige E-Mail-Adresse ist, und 404, wenn keine Sperrung passt.

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"
}