# Soppressioni API

> Consulta e gestisci gli indirizzi a cui Emailit non invierà.

URL di base: `https://api.emailit.com/v2`. Autenticati con `Authorization: Bearer <API key>`.

## Crea una soppressione — POST /suppressions

> Aggiungi un indirizzo alla lista di soppressione, in modo permanente o fino a una data a tua scelta, perché Emailit smetta di inviargli email.

# Crea una soppressione

Aggiunge un indirizzo alla lista di soppressione del workspace. Le email API e SMTP indirizzate a un indirizzo con una soppressione `recipient` ricevono lo stato `suppressed` invece di essere inviate, e le campagne saltano gli indirizzi soppressi. Richiede una chiave API con il permesso `full`.

`POST /suppressions`

## Corpo della richiesta

- `email` (string, obbligatorio): Indirizzo da sopprimere. Emailit lo salva in minuscolo.

- `type` (string): Tipo di soppressione. Il valore predefinito è `recipient`. Emailit usa `recipient`, `bounce`, `complaint` e `unsubscribe`. Solo le soppressioni `recipient` bloccano le email inviate tramite API e SMTP. Le campagne saltano ogni indirizzo con una soppressione attiva di qualsiasi tipo. Un indirizzo può avere una soppressione per ogni tipo.

- `reason` (string): Nota in testo libero, ad esempio `manual` o `Asked to stop receiving invoices`.

- `keep_until` (string | number | null): Quando scade la soppressione. Accetta un timestamp ISO 8601 (`2026-12-31T00:00:00Z`), un timestamp Unix in secondi (`1798675200`) o un’espressione in linguaggio naturale come `in 30 days` o `tomorrow at 9am`. Omettilo o invia `null` per una soppressione permanente. Dopo questo momento la soppressione non blocca più gli invii. Resta nella lista finché non la elimini.

## Restituisce

Restituisce `201 Created` con l’oggetto soppressione. Emailit invia anche un evento webhook [`suppression.created`](/it/docs/webhooks/events/suppression/created/).

| Stato | Quando |
| --- | --- |
| `400` | `email` non è un indirizzo valido o `keep_until` non può essere interpretato (il corpo contiene una stringa `error`), oppure manca `email` (errore di convalida standard). |
| `409` | L’indirizzo ha già una soppressione di questo tipo. Il corpo include la soppressione esistente in `existing`. |

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

---
Fonte: https://emailit.com/it/docs/api-reference/suppressions/create/

## Recupera una soppressione — GET /suppressions/{id}

> Recupera una soppressione tramite il suo ID o l’indirizzo email soppresso, con il tipo, il motivo e la scadenza.

# Recupera una soppressione

Restituisce una soppressione, cercata per ID o per indirizzo email. Richiede una chiave API con il permesso `full`.

`GET /suppressions/:id`

## Parametri di percorso

- `id` (string, obbligatorio): ID della soppressione (`sup_…`) o indirizzo soppresso. Codifica l’indirizzo per l’URL, ad esempio `ada%40example.com`. Un indirizzo può avere una soppressione per ogni tipo. Quando cerchi per indirizzo, Emailit ne restituisce una; usa l’ID per indicare un tipo specifico.

## Restituisce

Restituisce `200 OK` con l’oggetto soppressione. Una soppressione con `keep_until` nel passato non blocca più gli invii.

Restituisce `400` se `id` non è né un ID `sup_` né un indirizzo email valido, e `404` se nessuna soppressione corrisponde.

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

---
Fonte: https://emailit.com/it/docs/api-reference/suppressions/get/

## Aggiorna una soppressione — POST /suppressions/{id}

> Modifica l’indirizzo, il tipo, il motivo o la scadenza di una soppressione, cercata tramite il suo ID o l’indirizzo soppresso.

# Aggiorna una soppressione

Aggiorna una soppressione. Invia solo i campi che vuoi modificare; ne serve almeno uno. Richiede una chiave API con il permesso `full`.

`POST /suppressions/:id`

## Parametri di percorso

- `id` (string, obbligatorio): ID della soppressione (`sup_…`) o indirizzo soppresso, codificato per l’URL (`ada%40example.com`). Quando un indirizzo ha soppressioni di più tipi, usa l’ID.

## Corpo della richiesta

- `email` (string): Nuovo indirizzo. Viene salvato in minuscolo.

- `type` (string): Nuovo tipo: `recipient`, `bounce`, `complaint` o `unsubscribe`. Solo le soppressioni `recipient` bloccano gli invii tramite API e SMTP.

- `reason` (string): Nuovo motivo in testo libero.

- `keep_until` (string | number | null): Nuova scadenza, negli stessi formati accettati in [creazione](/it/docs/api-reference/suppressions/create/): ISO 8601, un timestamp Unix in secondi o un’espressione in linguaggio naturale come `in 30 days`. Invia `null` per rendere permanente la soppressione.

## Restituisce

Restituisce `200 OK` con la soppressione aggiornata. Emailit invia anche un evento webhook [`suppression.updated`](/it/docs/webhooks/events/suppression/updated/).

| Stato | Quando |
| --- | --- |
| `400` | Il corpo non contiene nessuno dei campi indicati sopra, `email` non è valido oppure `keep_until` non può essere interpretato. |
| `404` | Nessuna soppressione corrisponde a `id`. |
| `409` | Esiste già un’altra soppressione per il nuovo indirizzo e tipo. |

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

---
Fonte: https://emailit.com/it/docs/api-reference/suppressions/update/

## Elenca le soppressioni — GET /suppressions

> Elenca gli indirizzi soppressi del workspace con ricerca, filtri, ordinamento e paginazione per pagine.

# Elenca le soppressioni

Restituisce le soppressioni del workspace, a partire dalla più recente. L’elenco include le soppressioni che Emailit aggiunge automaticamente dopo bounce e segnalazioni, e le soppressioni scadute il cui `keep_until` è passato. Richiede una chiave API con il permesso `full`.

`GET /suppressions`

## Parametri di query

- `page` (integer): Numero di pagina, a partire da `1`. Il valore predefinito è `1`.

- `limit` (integer): Soppressioni per pagina, da `1` a `100`. Il valore predefinito è `10`.

- `search` (string): Corrispondenza sull’indirizzo o sul motivo, senza distinzione tra maiuscole e minuscole. `q` funziona come alias.

- `match` (string): `all` (predefinito) richiede che corrispondano tutti i filtri `key.condition`. Con `or` basta che ne corrisponda uno. Vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/).

- `sort` (string): Chiave di ordinamento: `email`, `reason`, `type` o `created_at` (predefinito).

- `order` (string): Direzione dell’ordinamento: `asc` o `desc` (predefinito).

## Filtri

Chiavi di filtro e di ordinamento: vedi [Filtri e ordinamento](https://emailit.com/it/docs/api-reference/filtering/).

In questo endpoint, `order` accetta solo `asc` o `desc`. Passa la chiave di ordinamento in `sort`, ad esempio `sort=email&order=asc`.

## Restituisce

Restituisce `200 OK` con le soppressioni in `data`, più `next_page_url` e `previous_page_url` (`null` quando non c’è una pagina successiva o precedente). Gli URL delle pagine mantengono la ricerca, i filtri e l’ordinamento.

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

---
Fonte: https://emailit.com/it/docs/api-reference/suppressions/list/

## Elimina una soppressione — DELETE /suppressions/{id}

> Rimuovi una soppressione tramite il suo ID o l’indirizzo soppresso, perché Emailit possa di nuovo inviare a quell’indirizzo.

# Elimina una soppressione

Elimina una soppressione perché l’indirizzo possa di nuovo ricevere email. Richiede una chiave API con il permesso `full`.

`DELETE /suppressions/:id`

## Parametri di percorso

- `id` (string, obbligatorio): ID della soppressione (`sup_…`) o indirizzo soppresso, codificato per l’URL (`ada%40example.com`). Una richiesta per indirizzo elimina una sola soppressione. Se l’indirizzo ha soppressioni di più tipi, eliminale una per una tramite ID, oppure ripeti la richiesta finché non restituisce `404`.

## Restituisce

Restituisce `200 OK` con `id` ed `email` della soppressione eliminata e `deleted: true`. Emailit invia anche un evento webhook [`suppression.deleted`](/it/docs/webhooks/events/suppression/deleted/).

Restituisce `400` se `id` non è né un ID `sup_` né un indirizzo email valido, e `404` se nessuna soppressione corrisponde.

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

---
Fonte: https://emailit.com/it/docs/api-reference/suppressions/delete/