Supressões

Consulte e gerencie os endereços para os quais o Emailit não envia e-mails.

URL basehttps://api.emailit.com/v2Autenticação Erros Limites de requisições

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

Criar uma supressão

Adiciona um endereço à lista de supressão do seu workspace. Os e-mails de API e SMTP para um endereço com uma supressão recipient recebem o status suppressed em vez de serem enviados, e as campanhas ignoram os endereços suprimidos. Requer uma chave de API com escopo full.

POST/suppressions

Corpo da requisição

emailstringObrigatório

Endereço a suprimir. O Emailit o armazena em minúsculas.

typestring

Tipo de supressão. Padrão: recipient. O Emailit usa recipient, bounce, complaint e unsubscribe.

Apenas as supressões recipient bloqueiam os e-mails enviados pela API e por SMTP. As campanhas ignoram todos os endereços com uma supressão ativa de qualquer tipo. Um endereço pode ter uma supressão por tipo.

reasonstring

Observação em texto livre, por exemplo manual ou Asked to stop receiving invoices.

keep_untilstring | number | null

Quando a supressão expira. Aceita um timestamp ISO 8601 (2026-12-31T00:00:00Z), um timestamp Unix em segundos (1798675200) ou linguagem natural em inglês, como in 30 days ou tomorrow at 9am. Omita-o ou envie null para uma supressão permanente.

Depois desse momento, a supressão deixa de bloquear os envios. Ela continua na lista até que você a exclua.

Retorno

Retorna 201 Created com o objeto de supressão. O Emailit também envia um evento de webhook suppression.created.

Status	Quando
`400`	`email` não é um endereço válido ou `keep_until` não pode ser interpretado (o corpo tem uma string `error`), ou `email` está ausente (erro de validação padrão).
`409`	O endereço já tem uma supressão deste tipo. O corpo inclui a supressão existente em `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
  }
}

Obter uma supressão

Retorna uma supressão, buscada pelo ID ou pelo endereço de e-mail. Requer uma chave de API com escopo full.

GET/suppressions/:id

Parâmetros de caminho

idstringObrigatório

ID da supressão (sup_…) ou o endereço suprimido. Codifique o endereço para URL, por exemplo ada%40example.com.

Um endereço pode ter uma supressão por tipo. Quando você busca pelo endereço, o Emailit retorna uma delas; use o ID para obter um tipo específico.

Retorno

Retorna 200 OK com o objeto de supressão. Uma supressão cujo keep_until já passou não bloqueia mais os envios.

Retorna 400 se id não for nem um ID sup_ nem um endereço de e-mail válido, e 404 se nenhuma supressão corresponder.

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

Atualizar uma supressão

Atualiza uma supressão. Envie apenas os campos que você quer alterar; pelo menos um é obrigatório. Requer uma chave de API com escopo full.

POST/suppressions/:id

Parâmetros de caminho

idstringObrigatório

ID da supressão (sup_…) ou o endereço suprimido, codificado para URL (ada%40example.com). Quando um endereço tiver supressões de vários tipos, use o ID.

Corpo da requisição

emailstring

Novo endereço. Armazenado em minúsculas.

typestring

Novo tipo: recipient, bounce, complaint ou unsubscribe. Apenas as supressões recipient bloqueiam os envios pela API e por SMTP.

reasonstring

Novo motivo, em texto livre.

keep_untilstring | number | null

Nova data de expiração, nos mesmos formatos aceitos na criação: ISO 8601, um timestamp Unix em segundos ou linguagem natural em inglês, como in 30 days. Envie null para tornar a supressão permanente.

Retorno

Retorna 200 OK com a supressão atualizada. O Emailit também envia um evento de webhook suppression.updated.

Status	Quando
`400`	O corpo não tem nenhum dos campos acima, `email` é inválido ou `keep_until` não pode ser interpretado.
`404`	Nenhuma supressão corresponde a `id`.
`409`	Já existe outra supressão para o novo endereço 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"
}

Listar supressões

Retorna as supressões do seu workspace, das mais recentes para as mais antigas. A listagem inclui as supressões que o Emailit adiciona automaticamente após bounces e reclamações, e as supressões expiradas cujo keep_until já passou. Requer uma chave de API com escopo full.

GET/suppressions

Parâmetros de consulta

pageinteger

Número da página, a partir de 1. Padrão: 1.

limitinteger

Supressões por página, de 1 a 100. Padrão: 10.

searchstring

Busca sem diferenciar maiúsculas de minúsculas no endereço ou no motivo. q funciona como alias.

matchstring

all (padrão) exige que todos os filtros key.condition correspondam. or aceita qualquer um deles. Consulte Filtragem.

sortstring

Chave de ordenação: email, reason, type ou created_at (padrão).

orderstring

Direção da ordenação: asc ou desc (padrão).

Filtros

Os filtros de listagem são um único nível de parâmetros de consulta key.condition=value. Consulte Filtragem para match, order, direction e a lista de condições por tipo.

Chaves de filtro

Chave	Tipo	Condições
`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

Chaves de ordenação

Este endpoint ordena com sort definido como uma destas chaves e order definido como asc ou desc (aqui, order=<key> retorna 400): email, reason, type, created_at, keep_until

Neste endpoint, order só aceita asc ou desc. Passe a chave de ordenação em sort, por exemplo sort=email&order=asc.

Retorno

Retorna 200 OK com as supressões em data, além de next_page_url e previous_page_url (null quando não há página seguinte ou anterior). As URLs das páginas mantêm a sua busca, os seus filtros e a sua ordenação.

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

Excluir uma supressão

Exclui uma supressão para que o endereço possa receber e-mails de novo. Requer uma chave de API com escopo full.

DELETE/suppressions/:id

Parâmetros de caminho

idstringObrigatório

ID da supressão (sup_…) ou o endereço suprimido, codificado para URL (ada%40example.com).

Uma requisição por endereço exclui uma supressão. Se o endereço tiver supressões de vários tipos, exclua cada uma pelo ID ou repita a requisição até que ela retorne 404.

Retorno

Retorna 200 OK com o id e o email da supressão excluída e deleted: true. O Emailit também envia um evento de webhook suppression.deleted.

Retorna 400 se id não for nem um ID sup_ nem um endereço de e-mail válido, e 404 se nenhuma supressão corresponder.

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