Autenticación

#Clave de API

Toda solicitud necesita una clave de API en el encabezado Authorization, con el formato Bearer:

Authorization: Bearer ps_4Fq9xLmT2vKp8sWd1Yc5Hf3Lz9Ag6Ej0Qm8rBnX

Las claves empiezan por ps_. Créalas en Claves de API en el panel, o por la API con POST /api-keys. El token completo aparece una sola vez, al crearla: Postal guarda solo el hash y los primeros caracteres (token_start), para que reconozcas la clave en la lista.

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

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

const data = await response.json();

import os
import requests

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

data = response.json()

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

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

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

#Permisos

Crear claves solo de envío o restringidas a un dominio depende del plan (restricted_api_keys); el número de claves también (api_keys). Consulta Límites.

Usa claves solo de envío en los sistemas que únicamente disparan correos electrónicos o eventos (el checkout, WordPress, el ERP) y reserva las de acceso total para automatizaciones de infraestructura. Si una clave de envío se filtra, no cambia tu configuración ni lee tus contactos, dominios o los correos de otras claves: solo ve lo que ella misma envió y los límites del plan.

#Errores de autenticación

#Idioma de los mensajes y origen de los cambios

Dos opciones por solicitud:

• Accept-Language: pt-BR (o en) elige el idioma del message de los errores y de los demás textos que la API escribe para tu solicitud (consulta la tabla de abajo). Sin el encabezado, viene en inglés. El name es siempre el mismo.
• X-Postal-Source: erp pone una etiqueta a los cambios que la clave hace en los contactos. La etiqueta aparece en source en los webhooks de contacto y en last_change_source del contacto, y permite que un webhook ignore lo que hizo el propio sistema.

El idioma de cada texto que escribe Postal depende de a quién va dirigido:

#Buenas prácticas

• Guarda la clave en una variable de entorno o en un gestor de secretos, nunca en el código. No uses la clave en el navegador ni en apps: cualquier persona podría copiarla. Llama a la API desde tu servidor.
• Usa una clave por sistema y por entorno. Así puedes revocar una sin tumbar las demás y ver en los registros quién hizo cada solicitud.
• Si una clave se filtra, elimínala de inmediato (DELETE /api-keys/{id}) y crea otra.
• Para dar a un asistente de IA acceso a la cuenta, prefiere el OAuth del servidor MCP, que limita el acceso a un equipo y a ámbitos, y se revoca sin cambiar de clave.