postal
Pedir acesso
Referência da API

Supressões

A lista de endereços que não recebem mais e-mails do seu time.

A lista de supressão guarda endereços que não devem mais receber e-mails do seu time. Bounces permanentes (bounce) e reclamações de spam (complaint) entram sozinhos; você também pode adicionar endereços (manual). Destinatários suprimidos são removidos do envio e geram o evento email.suppressed. Nos endpoints com {id}, você pode usar o ID ou o próprio endereço de e-mail.

#Listar supressões

GET/suppressions

Chave de acesso total

Aceita limit, after e before. source_id é o e-mail que gerou o bounce ou a reclamação.

GET /suppressions

cURL

curl https://api.postal.so/suppressions \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/suppressions', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/suppressions",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('suppressions', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Resposta
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "suppression",
      "id": "019a1530-6d7e-7f80-9a1b-2c3d4e5f6a7b",
      "email": "[email protected]",
      "origin": "bounce",
      "source_id": "019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b",
      "created_at": "2026-10-20T09:12:00.000000Z"
    }
  ]
}

#Adicionar um endereço

POST/suppressions

Chave de acesso total

Adiciona o endereço com origem manual. Se ele já estiver na lista, devolve o registro existente com status 200. Dispara suppression.added.

Corpo da requisição

  • emailstringobrigatório
    Endereço de e-mail, até 320 caracteres.

Erros

  • 422validation_error
    Algum campo é inválido. A mensagem diz qual.
POST /suppressions

cURL

curl -X POST https://api.postal.so/suppressions \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Node.js

const response = await fetch('https://api.postal.so/suppressions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://api.postal.so/suppressions",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "email": "[email protected]",
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->post('suppressions', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'email' => '[email protected]',
    ],
]);

$data = json_decode($response->getBody(), true);
201Resposta
{
  "object": "suppression",
  "id": "019a1c20-8f90-7aa1-8b2c-3d4e5f6a7b8c",
  "email": "[email protected]",
  "origin": "manual",
  "source_id": null,
  "created_at": "2026-10-20T09:12:00.000000Z"
}

#Adicionar em lote

POST/suppressions/batch/add

Chave de acesso total

Corpo da requisição

  • emailsstring[]obrigatório
    De 1 a 100 endereços.

Erros

  • 422validation_error
    Algum campo é inválido. A mensagem diz qual.
POST /suppressions/batch/add

cURL

curl -X POST https://api.postal.so/suppressions/batch/add \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["[email protected]", "[email protected]"]
  }'

Node.js

const response = await fetch('https://api.postal.so/suppressions/batch/add', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    emails: ['[email protected]', '[email protected]'],
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://api.postal.so/suppressions/batch/add",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "emails": ["[email protected]", "[email protected]"],
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->post('suppressions/batch/add', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'emails' => ['[email protected]', '[email protected]'],
    ],
]);

$data = json_decode($response->getBody(), true);
201Resposta
{
  "data": [
    {
      "object": "suppression",
      "id": "019a1c21-0a1b-7c2d-9e3f-4a5b6c7d8e9f"
    },
    {
      "object": "suppression",
      "id": "019a1c21-0a1c-7d3e-8f4a-5b6c7d8e9f0a"
    }
  ]
}

#Remover em lote

POST/suppressions/batch/remove

Chave de acesso total

Remove por endereço ou por ID (um dos dois). Itens que não estão na lista são ignorados.

Corpo da requisição

  • emailsstring[]
    De 1 a 100 endereços.
  • idsstring[]
    De 1 a 100 IDs. Use no lugar de emails.

Erros

  • 422validation_error
    Nenhum dos dois campos, ou os dois juntos.
POST /suppressions/batch/remove

cURL

curl -X POST https://api.postal.so/suppressions/batch/remove \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["[email protected]"]
  }'

Node.js

const response = await fetch('https://api.postal.so/suppressions/batch/remove', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    emails: ['[email protected]'],
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://api.postal.so/suppressions/batch/remove",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "emails": ["[email protected]"],
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->post('suppressions/batch/remove', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'emails' => ['[email protected]'],
    ],
]);

$data = json_decode($response->getBody(), true);
200Resposta
{
  "data": [
    {
      "object": "suppression",
      "id": "019a1c21-0a1b-7c2d-9e3f-4a5b6c7d8e9f",
      "deleted": true
    }
  ]
}

#Obter uma supressão

GET/suppressions/{id}

Chave de acesso total

Parâmetros de caminho

  • idstringobrigatório
    ID ou endereço de e-mail.

Erros

  • 404not_found
    O recurso não existe ou é de outro time.
GET /suppressions/{id}

cURL

curl https://api.postal.so/suppressions/[email protected] \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/suppressions/[email protected]', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/suppressions/[email protected]",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('suppressions/[email protected]', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Resposta
{
  "object": "suppression",
  "id": "019a1530-6d7e-7f80-9a1b-2c3d4e5f6a7b",
  "email": "[email protected]",
  "origin": "bounce",
  "source_id": "019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b",
  "created_at": "2026-10-20T09:12:00.000000Z"
}

#Remover um endereço

DELETE/suppressions/{id}

Chave de acesso total

O endereço volta a receber e-mails. Se ele foi suprimido por bounce, confirme antes que o problema foi resolvido. Dispara suppression.removed.

Parâmetros de caminho

  • idstringobrigatório
    ID ou endereço de e-mail.

Erros

  • 404not_found
    O recurso não existe ou é de outro time.
DELETE /suppressions/{id}

cURL

curl -X DELETE https://api.postal.so/suppressions/019a1530-6d7e-7f80-9a1b-2c3d4e5f6a7b \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/suppressions/019a1530-6d7e-7f80-9a1b-2c3d4e5f6a7b', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.delete(
    "https://api.postal.so/suppressions/019a1530-6d7e-7f80-9a1b-2c3d4e5f6a7b",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->delete('suppressions/019a1530-6d7e-7f80-9a1b-2c3d4e5f6a7b', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Resposta
{
  "object": "suppression",
  "id": "019a1530-6d7e-7f80-9a1b-2c3d4e5f6a7b",
  "deleted": true
}