Iniciar sesión Crear cuenta
Referencia de la API

Exportaciones

Archivos CSV con correos electrónicos, dominios, registros, claves y supresiones.

Genera archivos CSV con correos electrónicos, dominios, registros, claves de API, supresiones, contactos (las propiedades van en una columna en JSON), respuestas de un formulario o visitas de un formulario. La exportación se ejecuta en segundo plano: créala, consulta hasta que status sea completed y descárgala con download_url. Los archivos están disponibles durante 7 días y el enlace de descarga vale 1 hora (consulta de nuevo para generar otro). Exportar forma parte del plan (exports): sin él, la creación responde 403 plan_limit_reached.

#Listar exportaciones

GET/exports

Clave de acceso total

Acepta limit, after y before.

GET /exports

cURL

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

Node.js

const response = await fetch('https://api.postal.so/exports', {
  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/exports",
    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('exports', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Respuesta
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "export",
      "id": "019a1c10-7e8f-7a90-8b1c-2d3e4f5a6b7c",
      "type": "emails",
      "filters": {
        "status": "bounced"
      },
      "status": "completed",
      "rows": 312,
      "total_rows": 312,
      "error": null,
      "created_at": "2026-10-24T13:20:00.000000Z",
      "completed_at": "2026-10-24T13:20:04.000000Z",
      "expires_at": "2026-10-31T13:20:00.000000Z",
      "filename": "postal-emails-2026-10-24-132000.csv",
      "download_url": "https://api.postal.so/exports/019a1c10-7e8f-7a90-8b1c-2d3e4f5a6b7c/download?expires=1761315600&signature=7b1d…"
    }
  ]
}

#Crear una exportación

POST/exports

Clave de acceso total

Los filtros son los mismos de la lista correspondiente: correos electrónicos, dominios, registros, claves y contactos (las supresiones no tienen filtros). Para form_submissions y form_visits, el filtro form_id es obligatorio (un formulario por exportación) y el formulario debe existir (404 si no). Si una exportación igual sigue ejecutándose, se devuelve esa (estado 200) en lugar de crear otra. Cada equipo puede tener hasta 3 exportaciones en curso. En form_submissions, una respuesta escrita en la opción «Otro» sale como Outro: texto o Other: texto, en el idioma de la solicitud que creó la exportación (Accept-Language).

Cuerpo de la solicitud

  • typestringobligatorio
    emails, domains, logs, api_keys, suppressions, contacts, form_submissions o form_visits.
  • filtersobject
    Filtros de la lista, como {"status": "bounced", "start_date": "2026-10-01"}. En form_submissions, solo form_id. En form_visits: form_id y, opcionales, from y to (fecha, o fecha y hora; solo la fecha en to cubre el día completo).

Errores

  • 403plan_limit_reached
    El plan no incluye exportaciones.
  • 404not_found
    El formulario de form_id no existe.
  • 422validation_error
    Tipo o filtro no válido, o falta form_id.
  • 429rate_limit_exceeded
    Ya hay 3 exportaciones en curso.
POST /exports

cURL

curl -X POST https://api.postal.so/exports \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "emails",
    "filters": {
      "status": "bounced"
    }
  }'

Node.js

const response = await fetch('https://api.postal.so/exports', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'emails',
    filters: {
      status: 'bounced',
    },
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://api.postal.so/exports",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "type": "emails",
        "filters": {
            "status": "bounced",
        },
    },
    timeout=10,
)

data = response.json()

PHP

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

$response = $client->post('exports', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'type' => 'emails',
        'filters' => [
            'status' => 'bounced',
        ],
    ],
]);

$data = json_decode($response->getBody(), true);
201Respuesta
{
  "object": "export",
  "id": "019a1c10-7e8f-7a90-8b1c-2d3e4f5a6b7c",
  "type": "emails",
  "filters": {
    "status": "bounced"
  },
  "status": "pending",
  "rows": 0,
  "total_rows": null,
  "error": null,
  "created_at": "2026-10-24T13:20:00.000000Z",
  "completed_at": null,
  "expires_at": "2026-10-31T13:20:00.000000Z",
  "filename": "postal-emails-2026-10-24-132000.csv",
  "download_url": null
}

#Obtener una exportación

GET/exports/{id}

Clave de acceso total

Muestra el progreso (rows de total_rows) y, cuando está lista, el enlace de descarga. status: pending, processing, completed o failed (con error).

Parámetros de ruta

  • idstringobligatorio
    ID de la exportación.

Errores

  • 404not_found
    El recurso no existe o es de otro equipo.
GET /exports/{id}

cURL

curl https://api.postal.so/exports/019a1c10-7e8f-7a90-8b1c-2d3e4f5a6b7c \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/exports/019a1c10-7e8f-7a90-8b1c-2d3e4f5a6b7c', {
  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/exports/019a1c10-7e8f-7a90-8b1c-2d3e4f5a6b7c",
    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('exports/019a1c10-7e8f-7a90-8b1c-2d3e4f5a6b7c', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Respuesta
{
  "object": "export",
  "id": "019a1c10-7e8f-7a90-8b1c-2d3e4f5a6b7c",
  "type": "emails",
  "filters": {
    "status": "bounced"
  },
  "status": "completed",
  "rows": 312,
  "total_rows": 312,
  "error": null,
  "created_at": "2026-10-24T13:20:00.000000Z",
  "completed_at": "2026-10-24T13:20:04.000000Z",
  "expires_at": "2026-10-31T13:20:00.000000Z",
  "filename": "postal-emails-2026-10-24-132000.csv",
  "download_url": "https://api.postal.so/exports/019a1c10-7e8f-7a90-8b1c-2d3e4f5a6b7c/download?expires=1761315600&signature=7b1d…"
}