# Sperrungen API

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

Basis-URL: `https://api.emailit.com/v2`. Authentifizieren Sie sich mit `Authorization: Bearer <API key>`.

## Sperrung erstellen — POST /suppressions

> Setzen Sie eine Adresse dauerhaft oder bis zu einem gewählten Datum auf die Sperrliste, damit Emailit nicht mehr an sie sendet.

# 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

- `email` (string, erforderlich): Die zu sperrende Adresse. Emailit speichert sie in Kleinbuchstaben.

- `type` (string): 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.

- `reason` (string): Notiz als Freitext, zum Beispiel `manual` oder `Asked to stop receiving invoices`.

- `keep_until` (string | 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`](/de/docs/webhooks/events/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`. |

**Anfrage** `POST /suppressions`

**Node.js**

```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**

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

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

**PHP**

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

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

**Ruby**

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

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

**Go**

```go
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**

```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**

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

**.NET**

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

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

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

```bash
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"
  }'
```

**201**

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

**400**

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

**409**

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

---
Quelle: https://emailit.com/de/docs/api-reference/suppressions/create/

## Sperrung abrufen — GET /suppressions/{id}

> Rufen Sie eine Sperrung per ID oder gesperrter E-Mail-Adresse ab, mit Typ, Grund und Ablaufzeitpunkt.

# 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

- `id` (string, erforderlich): 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.

**Anfrage** `GET /suppressions/{id}`

**Node.js**

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

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

**Python**

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

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

**PHP**

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

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

**Ruby**

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

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

**Go**

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

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

**Rust**

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

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

**Java**

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

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

**.NET**

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

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

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

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

**200**

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

**400**

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

**404**

```json
{
  "error": "Suppression not found"
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/suppressions/get/

## Sperrung aktualisieren — POST /suppressions/{id}

> Ändern Sie Adresse, Typ, Grund oder Ablaufzeitpunkt einer Sperrung, gesucht per ID oder gesperrter Adresse.

# 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

- `id` (string, erforderlich): 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

- `email` (string): Neue Adresse. Wird in Kleinbuchstaben gespeichert.

- `type` (string): Neuer Typ: `recipient`, `bounce`, `complaint` oder `unsubscribe`. Nur Sperrungen vom Typ `recipient` stoppen Sendungen per API und SMTP.

- `reason` (string): Neuer Grund als Freitext.

- `keep_until` (string | number | null): Neuer Ablaufzeitpunkt, in denselben Formaten wie beim [Erstellen](/de/docs/api-reference/suppressions/create/): 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`](/de/docs/webhooks/events/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. |

**Anfrage** `POST /suppressions/{id}`

**Node.js**

```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**

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

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

**PHP**

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

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

**Ruby**

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

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

**Go**

```go
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**

```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**

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

**.NET**

```csharp
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" });
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

```bash
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"}'
```

**200**

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

**400**

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

**404**

```json
{
  "error": "Suppression not found"
}
```

**409**

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

---
Quelle: https://emailit.com/de/docs/api-reference/suppressions/update/

## Sperrungen auflisten — GET /suppressions

> Listen Sie die gesperrten Adressen Ihres Workspace auf, mit Suche, Filtern, Sortierung und seitenbasierter Paginierung.

# 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

- `page` (integer): Seitennummer, beginnend bei `1`. Standardwert: `1`.

- `limit` (integer): Sperrungen pro Seite, von `1` bis `100`. Standardwert: `10`.

- `search` (string): Abgleich mit Adresse oder Grund, ohne Beachtung der Groß-/Kleinschreibung. `q` funktioniert als Alias.

- `match` (string): `all` (Standardwert) verlangt, dass jeder Filter `key.condition` zutrifft. Bei `or` genügt einer davon. Siehe [Filtern und Sortieren](/de/docs/api-reference/filtering/).

- `sort` (string): Sortierschlüssel: `email`, `reason`, `type` oder `created_at` (Standardwert).

- `order` (string): Sortierrichtung: `asc` oder `desc` (Standardwert).

## Filter

Filter- und Sortierschlüssel: siehe [Filtern und Sortieren](https://emailit.com/de/docs/api-reference/filtering/).

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.

**Anfrage** `GET /suppressions`

**Node.js**

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

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

**Python**

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

suppressions = client.suppressions.list()
```

**PHP**

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

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

**Ruby**

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

suppressions = client.suppressions.list
```

**Go**

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

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

**Rust**

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

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

**Java**

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

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

**.NET**

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

var suppressions = emailit.Suppressions.List();
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

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

**200**

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

**401**

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

---
Quelle: https://emailit.com/de/docs/api-reference/suppressions/list/

## Sperrung löschen — DELETE /suppressions/{id}

> Entfernen Sie eine Sperrung per ID oder gesperrter Adresse, damit Emailit wieder an diese Adresse senden kann.

# 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

- `id` (string, erforderlich): 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`](/de/docs/webhooks/events/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.

**Anfrage** `DELETE /suppressions/{id}`

**Node.js**

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

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

**Python**

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

client.suppressions.delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")
```

**PHP**

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

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

**Ruby**

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

client.suppressions.delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e")
```

**Go**

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

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

**Rust**

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

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

**Java**

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

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

**.NET**

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

emailit.Suppressions.Delete("sup_2xL1c8NqT4pWm6Rb0YsKd3HvF9e");
```

**Laravel**

```php
use Emailit\Laravel\Facades\Emailit;

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

**cURL**

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

**200**

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

**400**

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

**404**

```json
{
  "error": "Suppression not found"
}
```

---
Quelle: https://emailit.com/de/docs/api-reference/suppressions/delete/