# Blokované adresy API

> Čtěte a spravujte adresy, na které Emailit nebude odesílat.

Základní URL: `https://api.emailit.com/v2`. Autentizujte se hlavičkou `Authorization: Bearer <API key>`.

## Vytvoření blokace — POST /suppressions

> Přidejte adresu na seznam blokovaných adres natrvalo, nebo do zvoleného data, aby na ni Emailit přestal odesílat.

# Vytvoření blokace

Přidá adresu na seznam blokovaných adres vašeho workspace. E-maily přes API a SMTP na adresu s blokací typu `recipient` se neodešlou, ale dostanou stav `suppressed`, a kampaně blokované adresy přeskakují. Vyžaduje API klíč s oprávněním `full`.

`POST /suppressions`

## Tělo požadavku

- `email` (string, povinné): Adresa, kterou chcete zablokovat. Emailit ji ukládá malými písmeny.

- `type` (string): Typ blokace. Výchozí hodnota je `recipient`. Emailit používá typy `recipient`, `bounce`, `complaint` a `unsubscribe`. E-maily odeslané přes API a SMTP zastaví jen blokace typu `recipient`. Kampaně přeskakují každou adresu s aktivní blokací jakéhokoli typu. Adresa může mít od každého typu jednu blokaci.

- `reason` (string): Poznámka ve volném textu, například `manual` nebo `Asked to stop receiving invoices`.

- `keep_until` (string | number | null): Kdy blokace vyprší. Přijímá časové razítko ISO 8601 (`2026-12-31T00:00:00Z`), unixové časové razítko v sekundách (`1798675200`) nebo přirozený jazyk, například `in 30 days` nebo `tomorrow at 9am`. Pro trvalou blokaci parametr vynechte, nebo pošlete `null`. Po uplynutí tohoto času blokace přestane bránit odesílání. Na seznamu zůstane, dokud ji nesmažete.

## Odpověď

Vrací `201 Created` s objektem blokace. Emailit také odešle webhookovou událost [`suppression.created`](/cs/docs/webhooks/events/suppression/created/).

| Stavový kód | Kdy |
| --- | --- |
| `400` | `email` není platná adresa nebo `keep_until` nelze zpracovat (tělo obsahuje řetězec `error`), nebo `email` chybí (standardní chyba validace). |
| `409` | Adresa už má blokaci tohoto typu. Tělo obsahuje existující blokaci v poli `existing`. |

**Požadavek** `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
  }
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/suppressions/create/

## Načtení blokace — GET /suppressions/{id}

> Načtěte blokaci podle jejího ID nebo podle blokované e-mailové adresy, včetně typu, důvodu a data vypršení.

# Načtení blokace

Vrací jednu blokaci dohledanou podle ID, nebo podle e-mailové adresy. Vyžaduje API klíč s oprávněním `full`.

`GET /suppressions/:id`

## Parametry v cestě

- `id` (string, povinné): ID blokace (`sup_…`), nebo blokovaná adresa. Adresu zakódujte pro URL, například `ada%40example.com`. Adresa může mít od každého typu jednu blokaci. Když hledáte podle adresy, Emailit vrátí jednu z nich; pro konkrétní typ použijte ID.

## Odpověď

Vrací `200 OK` s objektem blokace. Blokace, jejíž `keep_until` je v minulosti, už odesílání nebrání.

Pokud `id` není ID `sup_` ani platná e-mailová adresa, vrací `400`, a pokud žádná blokace neodpovídá, vrací `404`.

**Požadavek** `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"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/suppressions/get/

## Úprava blokace — POST /suppressions/{id}

> Změňte adresu, typ, důvod nebo datum vypršení blokace, kterou dohledáte podle jejího ID nebo podle blokované adresy.

# Úprava blokace

Upraví blokaci. Pošlete jen pole, která chcete změnit; alespoň jedno je povinné. Vyžaduje API klíč s oprávněním `full`.

`POST /suppressions/:id`

## Parametry v cestě

- `id` (string, povinné): ID blokace (`sup_…`), nebo blokovaná adresa zakódovaná pro URL (`ada%40example.com`). Pokud má adresa blokace více typů, použijte ID.

## Tělo požadavku

- `email` (string): Nová adresa. Ukládá se malými písmeny.

- `type` (string): Nový typ: `recipient`, `bounce`, `complaint` nebo `unsubscribe`. Odesílání přes API a SMTP zastaví jen blokace typu `recipient`.

- `reason` (string): Nový důvod ve volném textu.

- `keep_until` (string | number | null): Nové datum vypršení ve stejných formátech jako při [vytvoření](/cs/docs/api-reference/suppressions/create/): ISO 8601, unixové časové razítko v sekundách nebo přirozený jazyk, například `in 30 days`. Pokud má být blokace trvalá, pošlete `null`.

## Odpověď

Vrací `200 OK` s upravenou blokací. Emailit také odešle webhookovou událost [`suppression.updated`](/cs/docs/webhooks/events/suppression/updated/).

| Stavový kód | Kdy |
| --- | --- |
| `400` | Tělo neobsahuje žádné z výše uvedených polí, `email` je neplatný nebo `keep_until` nelze zpracovat. |
| `404` | Parametru `id` neodpovídá žádná blokace. |
| `409` | Pro novou adresu a typ už existuje jiná blokace. |

**Požadavek** `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"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/suppressions/update/

## Výpis blokovaných adres — GET /suppressions

> Vypište blokované adresy ve workspace s vyhledáváním, filtry, řazením a stránkováním po stránkách.

# Výpis blokovaných adres

Vrací blokace ve vašem workspace od nejnovějších. Seznam obsahuje i blokace, které Emailit přidává automaticky po nedoručeních a stížnostech, a vypršené blokace, jejichž `keep_until` už uplynulo. Vyžaduje API klíč s oprávněním `full`.

`GET /suppressions`

## Parametry dotazu

- `page` (integer): Číslo stránky, začíná na `1`. Výchozí hodnota je `1`.

- `limit` (integer): Počet blokací na stránce, od `1` do `100`. Výchozí hodnota je `10`.

- `search` (string): Hledá v adrese nebo v důvodu bez ohledu na velikost písmen. Jako alias funguje `q`.

- `match` (string): `all` (výchozí) vyžaduje shodu všech filtrů `key.condition`. U `or` stačí shoda kteréhokoli z nich. Viz [Filtrování a řazení](/cs/docs/api-reference/filtering/).

- `sort` (string): Klíč řazení: `email`, `reason`, `type` nebo `created_at` (výchozí).

- `order` (string): Směr řazení: `asc`, nebo `desc` (výchozí).

## Filtry

Klíče filtrů a řazení: viz [Filtrování](https://emailit.com/cs/docs/api-reference/filtering/).

U tohoto endpointu přijímá `order` jen `asc`, nebo `desc`. Klíč řazení předejte v `sort`, například `sort=email&order=asc`.

## Odpověď

Vrací `200 OK` s blokacemi v poli `data` a k tomu `next_page_url` a `previous_page_url` (`null`, když další nebo předchozí stránka neexistuje). URL stránek zachovávají vaše vyhledávání, filtry a řazení.

**Požadavek** `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"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/suppressions/list/

## Smazání blokace — DELETE /suppressions/{id}

> Odeberte blokaci podle jejího ID nebo podle blokované adresy, aby na tuto adresu mohl Emailit znovu odesílat.

# Smazání blokace

Smaže blokaci, aby adresa mohla znovu dostávat e-maily. Vyžaduje API klíč s oprávněním `full`.

`DELETE /suppressions/:id`

## Parametry v cestě

- `id` (string, povinné): ID blokace (`sup_…`), nebo blokovaná adresa zakódovaná pro URL (`ada%40example.com`). Požadavek podle adresy smaže jednu blokaci. Pokud má adresa blokace více typů, smažte každou podle ID, nebo požadavek opakujte, dokud nevrátí `404`.

## Odpověď

Vrací `200 OK` s poli `id` a `email` smazané blokace a `deleted: true`. Emailit také odešle webhookovou událost [`suppression.deleted`](/cs/docs/webhooks/events/suppression/deleted/).

Pokud `id` není ID `sup_` ani platná e-mailová adresa, vrací `400`, a pokud žádná blokace neodpovídá, vrací `404`.

**Požadavek** `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"
}
```

---
Zdroj: https://emailit.com/cs/docs/api-reference/suppressions/delete/