Soppressioni

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

URL di basehttps://api.emailit.com/v2Autenticazione Errori Limiti di frequenza

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

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

emailstringObbligatorio

Indirizzo da sopprimere. Emailit lo salva in minuscolo.

typestring

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.

reasonstring

Nota in testo libero, ad esempio manual o Asked to stop receiving invoices.

keep_untilstring | 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.

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

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

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

idstringObbligatorio

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.

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

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

idstringObbligatorio

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

emailstring

Nuovo indirizzo. Viene salvato in minuscolo.

typestring

Nuovo tipo: recipient, bounce, complaint o unsubscribe. Solo le soppressioni recipient bloccano gli invii tramite API e SMTP.

reasonstring

Nuovo motivo in testo libero.

keep_untilstring | number | null

Nuova scadenza, negli stessi formati accettati in creazione: 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.

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.

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

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

pageinteger

Numero di pagina, a partire da 1. Il valore predefinito è 1.

limitinteger

Soppressioni per pagina, da 1 a 100. Il valore predefinito è 10.

searchstring

Corrispondenza sull’indirizzo o sul motivo, senza distinzione tra maiuscole e minuscole. q funziona come alias.

matchstring

all (predefinito) richiede che corrispondano tutti i filtri key.condition. Con or basta che ne corrisponda uno. Vedi Filtri e ordinamento.

sortstring

Chiave di ordinamento: email, reason, type o created_at (predefinito).

orderstring

Direzione dell’ordinamento: asc o desc (predefinito).

Filtri

I filtri degli elenchi sono un unico livello di parametri di query key.condition=value. Vedi Filtri e ordinamento per match, order, direction e l’elenco delle condizioni per tipo.

Chiavi di filtro

Chiave	Tipo	Condizioni
`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

Chiavi di ordinamento

Questo endpoint ordina con sort impostato su una di queste chiavi e order impostato su asc o desc (qui order=<key> restituisce 400): email, reason, type, created_at, keep_until

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.

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

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

idstringObbligatorio

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.

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

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