Iniciar sesión Crear cuenta
Referencia de la API

Supresiones

La lista de direcciones que ya no reciben correos de tu equipo.

La lista de supresión guarda las direcciones que ya no deben recibir correos de tu equipo. Los rebotes permanentes (bounce) y las quejas de spam (complaint) entran automáticamente; también puedes añadir direcciones (manual). Los destinatarios suprimidos se quitan del envío y generan el evento email.suppressed. Una dirección de la lista tampoco llega nunca a ser contacto: la creación responde 422 email_suppressed y la importación la ignora. En los endpoints con {id}, puedes usar el ID o la propia dirección de correo.

#Listar supresiones

GET/suppressions

Clave de acceso total

Acepta limit, after y before. source_id es el correo que generó el rebote o la queja.

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);
200Respuesta
{
  "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"
    }
  ]
}

#Añadir una dirección

POST/suppressions

Clave de acceso total

Añade la dirección con origen manual. Si ya está en la lista, devuelve el registro existente con estado 200. Dispara suppression.added.

Cuerpo de la solicitud

  • emailstringobligatorio
    Dirección de correo, hasta 320 caracteres.

Errores

  • 422validation_error
    Algún campo no es válido. El mensaje indica cuál.
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);
201Respuesta
{
  "object": "suppression",
  "id": "019a1c20-8f90-7aa1-8b2c-3d4e5f6a7b8c",
  "email": "[email protected]",
  "origin": "manual",
  "source_id": null,
  "created_at": "2026-10-20T09:12:00.000000Z"
}

#Añadir por lotes

POST/suppressions/batch/add

Clave de acceso total

Cuerpo de la solicitud

  • emailsstring[]obligatorio
    De 1 a 100 direcciones.

Errores

  • 422validation_error
    Algún campo no es válido. El mensaje indica cuál.
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);
201Respuesta
{
  "data": [
    {
      "object": "suppression",
      "id": "019a1c21-0a1b-7c2d-9e3f-4a5b6c7d8e9f"
    },
    {
      "object": "suppression",
      "id": "019a1c21-0a1c-7d3e-8f4a-5b6c7d8e9f0a"
    }
  ]
}

#Quitar por lotes

POST/suppressions/batch/remove

Clave de acceso total

Quita por dirección o por ID (uno de los dos). Los elementos que no están en la lista se ignoran.

Cuerpo de la solicitud

  • emailsstring[]
    De 1 a 100 direcciones.
  • idsstring[]
    De 1 a 100 IDs. Úsalo en lugar de emails.

Errores

  • 422validation_error
    Ninguno de los dos campos, o los dos a la vez.
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);
200Respuesta
{
  "data": [
    {
      "object": "suppression",
      "id": "019a1c21-0a1b-7c2d-9e3f-4a5b6c7d8e9f",
      "deleted": true
    }
  ]
}

#Obtener una supresión

GET/suppressions/{id}

Clave de acceso total

Parámetros de ruta

  • idstringobligatorio
    ID o dirección de correo.

Errores

  • 404not_found
    El recurso no existe o es de otro equipo.
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);
200Respuesta
{
  "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"
}

#Quitar una dirección

DELETE/suppressions/{id}

Clave de acceso total

La dirección vuelve a recibir correos. Si se suprimió por un rebote, confirma antes que el problema se resolvió. Dispara suppression.removed.

Parámetros de ruta

  • idstringobligatorio
    ID o dirección de correo.

Errores

  • 404not_found
    El recurso no existe o es de otro equipo.
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);
200Respuesta
{
  "object": "suppression",
  "id": "019a1530-6d7e-7f80-9a1b-2c3d4e5f6a7b",
  "deleted": true
}