Referencia de la API

Registros

El registro de cada solicitud hecha con una clave de API y de cada envío por SMTP.

Cada solicitud hecha con una clave de API, y cada mensaje recibido por SMTP, queda registrada con el cuerpo enviado y la respuesta. Los contenidos de adjuntos y los textos de más de 5.000 caracteres se recortan. Las solicitudes hechas desde el panel no entran en los registros. Los registros se guardan durante 30 días. Un envío por SMTP aparece con method SMTP y endpoint /smtp: el cuerpo trae el remitente, los destinatarios del sobre, el asunto, el tamaño y la cantidad de adjuntos, y la respuesta trae el id del correo electrónico (o el motivo del rechazo).

#Listar registros

GET/logs

Clave de acceso total

Parámetros de consulta

limitinteger
De 1 a 100. Predeterminado: 20.
afterstring
Cursor de la página siguiente.
beforestring
Cursor de la página anterior.
statusstring
Status HTTP o rangos separados por comas, como 4xx,500.
methodstring
Métodos separados por comas, como POST,PATCH. Los envíos SMTP usan el método SMTP.
sourcestring
api o smtp.
user_agentstring
Parte del User-Agent.
api_key_idstring
Solo solicitudes de una clave.
searchstring
Búsqueda en la ruta, como /emails/batch.
start_datestring
A partir de esta fecha (ISO 8601, inclusive). Sin zona horaria, se usa UTC.
end_datestring
Hasta esta fecha (ISO 8601, inclusive). Con solo la fecha, cubre el día completo. Si es anterior a start_date, la respuesta es 422. Consulta los filtros de fecha.

Errores

422validation_error
Algún campo no es válido. El mensaje indica cuál.

GET /logs

cURL

curl 'https://api.postal.so/logs?status=4xx&source=api' \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/logs?status=4xx&source=api', {
  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/logs",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    params={
        "status": "4xx",
        "source": "api",
    },
    timeout=10,
)

data = response.json()

PHP

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

$response = $client->get('logs', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'query' => [
        'status' => '4xx',
        'source' => 'api',
    ],
]);

$data = json_decode($response->getBody(), true);

200Respuesta

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1b2d-0000-7b11-a2c3-d4e5f6a7b8c9",
      "created_at": "2026-10-24T13:02:11.000000Z",
      "endpoint": "/emails",
      "method": "POST",
      "response_status": 422,
      "user_agent": "node-fetch/1.0",
      "api_key_id": "0199f0e2-7b8c-7d9e-8f0a-1b2c3d4e5f6a"
    }
  ]
}

#Obtener un registro

GET/logs/{id}

Clave de acceso total

Devuelve el registro con request_body (el JSON enviado, o la query string en solicitudes GET) y response_body.

Parámetros de ruta

idstringobligatorio
ID del registro.

Errores

404not_found
El recurso no existe o es de otro equipo.

GET /logs/{id}

cURL

curl https://api.postal.so/logs/019a1b2c-4d60-7a11-b2c3-d4e5f6a7b8c9 \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/logs/019a1b2c-4d60-7a11-b2c3-d4e5f6a7b8c9', {
  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/logs/019a1b2c-4d60-7a11-b2c3-d4e5f6a7b8c9",
    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('logs/019a1b2c-4d60-7a11-b2c3-d4e5f6a7b8c9', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

200Respuesta

{
  "object": "log",
  "id": "019a1b2c-4d60-7a11-b2c3-d4e5f6a7b8c9",
  "created_at": "2026-10-24T13:02:11.000000Z",
  "endpoint": "/emails",
  "method": "POST",
  "response_status": 200,
  "user_agent": "node-fetch/1.0",
  "api_key_id": "0199f0e2-7b8c-7d9e-8f0a-1b2c3d4e5f6a",
  "request_body": {
    "from": "Loja Exemplo <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Seu pedido #10482 saiu para entrega",
    "html": "<p>O pedido <b>#10482</b> está a caminho.</p>"
  },
  "response_body": {
    "id": "019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b"
  }
}