# Postal

> Postal is a transactional and marketing email platform for the Brazilian market, with a REST API (JSON), SMTP, signed webhooks, verified domains, contacts, segments, topics, event-driven automations and the option to process email in São Paulo.

## The essentials

- API base URL: `https://api.postal.so`.
- Authentication: `Authorization: Bearer ps_...` header (API key). Full-access or sending-only keys (`POST /emails`, `POST /emails/batch`, `POST /events`, SMTP; a sending-only key also reads `GET /emails/{id}` for the emails it sent itself, with 404 for the others, and `GET /usage`).
- Errors: `{"statusCode", "name", "message"}`; handle them by `name` (a stable English code such as `validation_error`).
- Lists: cursor pagination with `limit`, `after`, `before` and `has_more`.
- Idempotency: `Idempotency-Key` header (1 to 256 characters, 24 hours) on `POST /emails`, `POST /emails/batch` and `POST /events`.
- Webhooks: Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`), HMAC-SHA256 with the `signing_secret` (`whsec_...`).
- SDKs: Node.js (`npm install postal-so`) and PHP/Laravel (`composer require postal-so/postal-php`). CLI: `postal`, in the `postal-so` package.
- Laravel: the PHP package registers the `postal` mail transport by itself (`MAIL_MAILER=postal`, `POSTAL_API_KEY=ps_...`), so `Mail::to()->send()`, notifications and Mailables go out through the API. See [SDKs, Laravel section (in Portuguese)](https://postal.so/docs/sdks#laravel).
- Resend compatible: the same `POST /emails`, errors, pagination, idempotency and event names. Resend SDKs work when `baseUrl` (or `RESEND_BASE_URL`) points to `https://api.postal.so`. See [Migrate from Resend (in Portuguese)](https://postal.so/migrar/resend).
- Request rate limit per second, per team (all keys added up): Free 5, Pro 10, Scale 20, Enterprise 50. `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers; 429 `rate_limit_exceeded` with `Retry-After`. Your team value is in `GET /usage` (`rate_limit`, also with a sending-only key) and in the `X-RateLimit-*` headers of every response.
- Sending quotas: Free 100 per day and 3,000 per month; Pro 50,000 per month; Scale 100,000 per month; Enterprise custom. The daily limit in force is the lower of the plan's and the account reputation ceiling (500, 2,000, 5,000 and 10,000 a day at levels 1 to 4; new accounts start at level 1). The day resets at 00:00 UTC. When reached: 429 `daily_quota_exceeded` or `monthly_quota_exceeded` (SMTP: 452 4.5.3). On plans that offer the Sends add-on, a reserve paid once (`GET /billing/email-credits`, `emails.credits` in `GET /usage`) covers what goes past the monthly quota before the 429; the daily limit still applies and broadcasts do not use the reserve. See [Limits (in Portuguese)](https://postal.so/docs/limites) and [Sends add-on (in Portuguese)](https://postal.so/docs/painel/adicional-de-envios).
- Sizes: up to 50 recipients in `to`, 100 emails per batch, 40 MB of attachments per email, scheduling up to 30 days ahead, `Idempotency-Key` of 256 characters for 24 hours, 30-day retention for emails, webhooks and logs.
- Account reputation and pause: each team has a score from 0 to 100 (new accounts start at 0) that goes up with clean sending days and down with bad days and pauses; the level (1 to 5) sets the daily ceiling and the bounce limit. Permanent bounces above the level limit (3% at level 1, 4% at level 2 and 5% from level 3 up), complaints above 0.3% or rejected content above 5% (7 days; at levels 1 to 3 also 24 hours, and bounces of every type above 15%) pause the team sending with 403 `sending_paused`. Before that, owners and admins get a warning email. `GET /usage` has `reputation` and `sending` (`paused`, `reason`, `reason_code`, `reason_details`), and the `sending.paused` and `sending.resumed` webhooks carry the same state (`reason_code`: `bounce_rate`, `complaint_rate`, `content_rejected`, `all_bounce_rate` or `manual`). See [Account reputation (in Portuguese)](https://postal.so/docs/painel/reputacao-da-conta).
- Suppression list: a permanent bounce and a complaint add the address by themselves. To send again, `DELETE /suppressions/{id}` or `POST /suppressions/batch/remove`; to import from another provider, `POST /suppressions/batch/add` (100 at a time).
- Templates: full API at `/templates` (create, update, publish, duplicate, test, versions and restore), with `{{{VAR}}}` variables. See [Templates (in Portuguese)](https://postal.so/docs/api/templates).
- Webhooks: 8 attempts over about 27 hours, always with the same `webhook-id`; the same values also in `svix-id`, `svix-timestamp` and `svix-signature`.
- Inboxes: received messages become conversations (`/inboxes/{id}/threads`) with folders, labels, an assignee and drafts; replying and sending from the inbox accepts `attachments` (up to 10 Base64 files, 40 MB in total) and there is an optional AI agent (`POST /inboxes/{id}/agent/improve-instructions` improves its instructions). Webhooks: `email.received`, `inbox.thread.created`, `inbox.thread.updated`, `inbox.thread.deleted` and `inbox.draft.created`. See [Received emails and inboxes (in Portuguese)](https://postal.so/docs/api/recebidos).
- Test addresses (like Resend `delivered@resend.dev`): emails sent only to `delivered@`, `bounced@`, `complained@`, `suppressed@` or `delayed@` at `sandbox.postal.so` (they accept `+label`, e.g. `delivered+order123@sandbox.postal.so`) are accepted like any other but never delivered: Postal records the events (`email.sent` and `email.delivered`; `bounced`: sent and a permanent `email.bounced`; `complained`: sent, delivered and `email.complained`; `suppressed`: only `email.suppressed`; `delayed`: sent and `email.delivery_delayed`) and fires the webhooks for real. They use no quota, do not enter the suppression list or the reputation rates, and the email has `simulated: true`. Do not mix them with real recipients (422). See [Test addresses (in Portuguese)](https://postal.so/docs/api/emails#enderecos-de-teste).
- OTP-Token: the `OTP-Token: "123456"; origin="https://app.example.com"` header (an individual Internet-Draft, `draft-goto-otp-token-01`, not a standard; support in mail clients is up to them) hands over a one-time code in a machine-readable way, bound to an origin. Send it in `headers` of `POST /emails` (batch, templates and scheduled emails too) or by SMTP, without encoding the value; the API validates it (422) and refuses duplicates. The SDKs have `otpTokenHeader(code, origin)` (Node.js) and `Postal\OtpToken::header($code, $origin)` (PHP). On received emails, `otp_token` is `{code, origin}` or `null` (strict reading; not in the `email.received` webhook). See [OTP-Token header](https://postal.so/en/docs/otp-token).
- Sending regions per domain: `sa-east-1` (Sao Paulo, default), `us-east-1`, `us-east-2`, `eu-west-1` and `ap-northeast-1`.
- Plans, prices and limits: `GET /plans` (public, no key) and [postal.so/precos](https://postal.so/precos) (in Portuguese). Billing in reais, US dollars or euros. The same prices as always-current Markdown for AI agents: [postal.so/pricing.md](https://postal.so/pricing.md) or `GET https://api.postal.so/plans.md?lang=pt|en|es`.
- The full text of the documentation, in one file: [llms-full.en.txt](https://postal.so/llms-full.en.txt) (only the pages already translated; the rest is in Portuguese in [llms-full.txt](https://postal.so/llms-full.txt)). Portuguese summary: [llms.txt](https://postal.so/llms.txt).

## Getting started

- [Introduction](https://postal.so/en/docs): Postal API documentation: transactional email by API and SMTP, webhooks, domains and the full reference.
- [Authentication](https://postal.so/en/docs/autenticacao): How to authenticate with the Postal API using Bearer API keys: full-access and sending-only permissions, domain-restricted keys, auth errors and best practices.
- [Getting started](https://postal.so/en/docs/primeiros-passos): Send your first email with the Postal API in cURL, Node.js, Python, PHP or Laravel: verify a domain, create an API key and track the delivery.

## Concepts

- [Errors](https://postal.so/en/docs/erros): Postal API error response format, every error code and name, and when to retry: HTTP status, rate limits, quotas and validation errors.
- [Pagination and filters](https://postal.so/en/docs/paginacao): Cursor pagination (limit, after, before, has_more) and list filters in the Postal API, with examples in cURL, Node.js, Python and PHP.
- [Limits](https://postal.so/en/docs/limites): Postal API rate limits, daily and monthly sending quotas by plan, sending reputation thresholds and maximum sizes for attachments, batches and more.
- [Idempotency](https://postal.so/en/docs/idempotencia): Use the Idempotency-Key header to retry Postal send requests without duplicating emails: rules, the 24-hour window, errors and how to choose a key.

## Guides

- [Webhooks](https://postal.so/en/docs/webhooks): Postal webhook events, payload formats, Standard Webhooks signature verification (HMAC-SHA256) in Node.js, Python and PHP, retries and automatic disabling.
- [SMTP](https://postal.so/en/docs/smtp): Postal SMTP relay settings: smtp.postal.so, ports 465 and 587, username postal and an API key as the password. Examples for Nodemailer, Python, PHP and Laravel.
- [OTP-Token header](https://postal.so/en/docs/otp-token): Guide to the OTP-Token email header (IETF draft-goto-otp-token): format, validation, sending by API, SMTP and SDKs, reading otp_token and security.
- [Domains and DNS](https://postal.so/en/docs/dominios-e-dns): How to set up DNS for your sending domain with Postal: DKIM, SPF, Return-Path MX, DMARC, tracking CNAME, inbound MX, verification status and regions.
- [Email marketing](https://postal.so/en/docs/marketing-por-email): Email marketing best practices with Postal: consent, LGPD, unsubscribe link, one-click List-Unsubscribe, preference page, topics and deliverability.
- [Integrate your app](https://postal.so/en/docs/integre-seu-app): Connect Stripe, Supabase, Clerk, Auth0 or Firebase to Postal: sign-ups and payments become contacts and events, and login emails go out through Postal.
- [CRM connections](https://postal.so/en/docs/crm): Postal CRM connections: HubSpot, Pipedrive and RD Station CRM, sync direction, field and stage mapping, sync log, API, limits and errors.
- [CRM by webhook](https://postal.so/en/docs/crm-webhook): Postal CRM connection by webhook: signature, body format, field mapping, outbound payloads, responses, retries and examples.
- [MCP server](https://postal.so/en/docs/mcp): Postal MCP server at api.postal.so/mcp: how to connect AI assistants, OAuth or API key authentication, scopes, the 34 tools, examples and errors.
- [SDKs](https://postal.so/en/docs/sdks): Official Postal SDKs for Node.js, PHP and Laravel: send email, manage contacts and events, verify webhook signatures and use the Laravel mail transport.
- [CLI](https://postal.so/en/docs/cli): The postal CLI: log in, send emails and events, upsert contacts and verify domains from the terminal, with JSON output and exit codes for scripts.

## Dashboard guide

- [Overview (in Portuguese)](https://postal.so/docs/painel/visao-geral)
- [Emails (in Portuguese)](https://postal.so/docs/painel/emails)
- [Templates (in Portuguese)](https://postal.so/docs/painel/modelos)
- [Inboxes (in Portuguese)](https://postal.so/docs/painel/caixas-de-entrada)
- [Logs (in Portuguese)](https://postal.so/docs/painel/logs)
- [Audience (in Portuguese)](https://postal.so/docs/painel/audiencia)
- [Automatic audience (in Portuguese)](https://postal.so/docs/painel/audiencia-automatica)
- [Campaigns (in Portuguese)](https://postal.so/docs/painel/campanhas)
- [Automations (in Portuguese)](https://postal.so/docs/painel/automacoes)
- [Forms (in Portuguese)](https://postal.so/docs/painel/formularios)
- [Email validation (in Portuguese)](https://postal.so/docs/painel/validacao-de-emails)
- [Metrics (in Portuguese)](https://postal.so/docs/painel/metricas)
- [Domains (in Portuguese)](https://postal.so/docs/painel/dominios)
- [API keys (in Portuguese)](https://postal.so/docs/painel/chaves-de-api)
- [Webhooks (in Portuguese)](https://postal.so/docs/painel/webhooks)
- [Suppressions (in Portuguese)](https://postal.so/docs/painel/supressoes)
- [Integrations (in Portuguese)](https://postal.so/docs/painel/integracoes)
- [Settings (in Portuguese)](https://postal.so/docs/painel/configuracoes)
- [Account reputation (in Portuguese)](https://postal.so/docs/painel/reputacao-da-conta)
- [Sends add-on (in Portuguese)](https://postal.so/docs/painel/adicional-de-envios)
- [Contacts add-on (in Portuguese)](https://postal.so/docs/painel/adicional-de-contatos)
- [Profile (in Portuguese)](https://postal.so/docs/painel/perfil)
- [Help (in Portuguese)](https://postal.so/docs/painel/ajuda)

## API reference

- [Emails](https://postal.so/en/docs/api/emails): Send email API reference: POST /emails and /emails/batch, attachments, tags, headers, templates, scheduling, test addresses and delivery status.
- [Received emails and inboxes](https://postal.so/en/docs/api/recebidos): Inbound email API reference: create inboxes, read received emails, threads, labels, drafts, forwarding, the AI agent and inbox webhooks.
- [Domains](https://postal.so/en/docs/api/dominios): Domains API reference: add sending domains, DKIM, SPF and tracking DNS records, verification, receiving and domain claims.
- [API keys](https://postal.so/en/docs/api/chaves-de-api): API keys reference: create full-access or sending-only keys, restrict a key to one domain, rename and revoke it. The token is shown only once.
- [Templates](https://postal.so/en/docs/api/templates): Email templates API reference: create templates with variables, publish and restore versions, send tests, duplicate and upload images.
- [Webhooks](https://postal.so/en/docs/api/webhooks): Webhooks API reference: create and manage webhook endpoints, rotate the signing secret, send test events, list deliveries and attempts, and replay events.
- [Suppressions](https://postal.so/en/docs/api/supressoes): Suppression list API reference: list, add and remove suppressed addresses one by one or in bulk. Bounces and spam complaints are added automatically.
- [Logs](https://postal.so/en/docs/api/logs): API request logs reference: list and filter the requests made with your API keys and the messages sent over SMTP, with request and response bodies.
- [Exports](https://postal.so/en/docs/api/exportacoes): CSV exports API reference: export emails, domains, logs, API keys, suppressions or contacts to CSV, follow the progress and download the file.
- [Usage and metrics](https://postal.so/en/docs/api/uso): Usage and email metrics API reference: plan quotas and rate limit, plus delivery, open, click, bounce and complaint rates by period, domain or broadcast.
- [AI](https://postal.so/en/docs/api/ia): AI API reference: write emails, improve text, suggest subjects, explain deliverability and build automations with asynchronous tasks and credits.
- [Plans](https://postal.so/en/docs/api/planos): Plans API reference: GET /plans returns plans, prices in BRL, USD and EUR, overage prices and limits with no API key needed, plus the endpoints to view the Sends add-on reserve and buy a pack, and to view, quote and change a team's Contacts add-on.

## Audience

- [Contacts](https://postal.so/en/docs/api/contatos): Contacts API reference: create, list, update and delete contacts, manage their segments and topic subscriptions, and how suppressed addresses are handled.
- [Contact properties](https://postal.so/en/docs/api/propriedades-de-contato): Contact properties API reference: define custom contact fields with a type and a default value, and how string, number, boolean and date values are converted.
- [Contact import](https://postal.so/en/docs/api/importacao-de-contatos): Import contacts from a CSV file with the Postal API: column mapping, segments and topics, background processing, progress and per-row errors.
- [Segments](https://postal.so/en/docs/api/segmentos): Segments API reference: create, list, update and delete segments, the lists of contacts you target with email broadcasts.
- [Topics](https://postal.so/en/docs/api/topicos): Topics API reference: manage the subjects contacts opt in or out of, with opt-in or opt-out defaults and public or private visibility.
- [Forms](https://postal.so/en/docs/api/formularios): Signup forms API reference: create hosted forms, embed them in HTML or submit from JavaScript, with double opt-in, CORS and spam protection.
- [Email verification](https://postal.so/en/docs/api/verificacao-de-emails): Email verification API reference: check one address, estimate and preview a list, verify a CSV, a segment or all contacts, read the results and apply them to contacts.

## Marketing

- [Broadcasts](https://postal.so/en/docs/api/broadcasts): Broadcasts API reference: create, personalize, test, schedule and send marketing emails to segments and topics, with unsubscribe and delivery stats.
- [Automations](https://postal.so/en/docs/api/automacoes): Automations API reference: triggers, wait, wait_for, send email, condition and webhook steps, A/B experiments, scheduling, versions and run logs.
- [Events](https://postal.so/en/docs/api/eventos): Events API reference: send custom events with an idempotency key to start automations, list event names and query the last 90 days of events.

## Integrations

- [Stripe](https://postal.so/en/docs/integracoes/stripe): Postal Stripe integration: webhooks for customers, subscriptions, invoices and disputes become contacts and events that trigger email automations.
- [Supabase](https://postal.so/en/docs/integracoes/supabase): Postal Supabase integration: Database Webhooks on auth.users create contacts and events, and the Send Email Hook sends login emails through Postal.
- [Clerk](https://postal.so/en/docs/integracoes/clerk): Postal Clerk integration: Clerk webhooks for users and the waitlist become Postal contacts and events, verified with Svix signatures.
- [Auth0](https://postal.so/en/docs/integracoes/auth0): Postal Auth0 integration: a Log Stream turns sign-ups and logins into contacts and events, and a custom email provider Action sends Auth0 emails.
- [Firebase Auth](https://postal.so/en/docs/integracoes/firebase): Postal Firebase Authentication integration: two Cloud Functions send every created or deleted user to Postal as a contact and an event.
- [Better Auth](https://postal.so/en/docs/integracoes/better-auth): How to send Better Auth emails with the Postal API: verification, password reset and magic link, with a sending-only key and optional templates.
- [Auth.js (NextAuth)](https://postal.so/en/docs/integracoes/authjs): How to send Auth.js (NextAuth) email sign-in links with the Postal API: a custom email provider with sendVerificationRequest.

## For AI agents

- [Postal skill](https://raw.githubusercontent.com/postalhq/postal-node/main/skills/postal/SKILL.md): teaches Claude Code, Codex and Cursor to integrate Postal in an app (install the SDK, API key, emails, events, contacts and webhooks).
- [Node.js SDK](https://github.com/postalhq/postal-node): `postal-so` package, with the `postal` CLI.
- [PHP and Laravel SDK](https://github.com/postalhq/postal-php): `postal-so/postal-php` package, with the `postal` mail transport for Laravel.