API Reference

Authentication

All API requests require an Authorization header with your sender API key. Get your key from the dashboard.

Authorization: Bearer nexo_sk_YOUR_API_KEY

Base URL: https://postalprivado.com/api/v1

Every POST request also requires an Idempotency-Key header (UUID recommended). Repeated calls with the same key within 24h return the original response without re-sending.

Quickstart

Send your first message in one curl command:

# Email is required — it carries the full message and identifies the recipient.
curl -X POST https://postalprivado.com/api/v1/send \
  -H "Authorization: Bearer nexo_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "recipient": { "email": "alumno@correduria.es" },
    "envelope": {
      "subject": "Acceso a tu plataforma de formación",
      "body": "Hola, aquí tienes tu enlace: https://plataforma.example.com/login?token=abc123"
    }
  }'

# Optional: add phone_e164 so the recipient can enable an SMS heads-up in
# their portal. The SMS never carries the message — it only invites them to
# check their email.
#   "recipient": { "email": "alumno@correduria.es", "phone_e164": "+34600123456" }

The message is delivered to the recipient's email immediately — no consent step. You get message.delivered when it is sent and message.confirmed when it is opened.

POST /v1/send

Submit a message for delivery.

Request body

Response (202 Accepted)

{
  "message_id": "04b6bad3-6378-41cb-8a42-d41bf052d269",
  "state": "accepted",             // queued for email delivery
  "expires_at": "2026-05-18T09:43:19.597+00:00",
  "consent_required": false,       // direct delivery — no consent step
  "consent_request_id": null
}

Error responses

Message states

Messages transition through states as they are processed. Terminal states will not change.

Message content is retained encrypted at rest (AES-256-GCM, per-recipient keys) together with its delivery evidence trail. Recipients can request erasure under GDPR; any administrative decryption outside the normal request path is audited.

GET /v1/messages/:id

Poll the status of a message.

curl https://postalprivado.com/api/v1/messages/MSG_ID \
  -H "Authorization: Bearer nexo_sk_YOUR_API_KEY"

{
  "id": "04b6bad3-6378-41cb-8a42-d41bf052d269",
  "state": "delivered",
  "created_at": "2026-05-11T09:43:19.597Z",
  "expires_at": "2026-05-18T09:43:19.597Z",
  "delivered_at": "2026-05-11T09:44:02.118Z",
  "channel_used": "email",
  "external_ref": null
}

Polling is supported but webhooks are strongly recommended for production — they fire within seconds of a state change.

Delivery flow

Postal Privado delivers every message to the recipient's email — no consent step. Identity-verified (KYC) senders deliver directly, and the recipient controls everything from their portal.

1. Send → delivered: The message goes out by email immediately. State moves accepted → delivering → delivered, with a webhook at each stage. delivered means the email was handed to the mail provider.
2. Read receipt: When the recipient opens the email, state becomes confirmed and you receive message.confirmed. Open tracking is best-effort — it can be inflated by Apple Mail Privacy Protection or blocked by privacy proxies — so treat it as evidence, not proof.
3. Bounce or complaint: If the email bounces or is marked as spam, state flips to failed with message.failed — the optimistic delivered is corrected.
4. SMS heads-up (optional): If you include phone_e164 and the recipient enables it in their portal, they also get a short SMS telling them to check their email. The SMS never carries the message body.
5. Blocking: A recipient can block your app from their portal. Sends to a blocked recipient return immediately with state: "rejected" and message.rejected — no email is sent.

Webhooks

Configure a webhook URL in your dashboard settings to receive real-time event notifications.

Events

Payload

{
  "event": "message.delivered",
  "message_id": "04b6bad3-6378-41cb-8a42-d41bf052d269",
  "external_ref": "your-internal-id-or-null",
  "state": "delivered",
  "ack_tier": "best_effort",
  "channel_used": "email",
  "timestamp": "2026-05-11T09:44:02.118Z",
  "evidence_summary": { "type": "provider_ack", "provider": "resend" }
}

Verifying signatures

Each webhook request includes an X-Nexo-Signature header (HMAC-SHA256 of the raw body). Verify with your webhook secret:

import crypto from "crypto";

function verifyWebhook(rawBody: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express example
app.post("/webhooks/postal-privado", express.raw({ type: "*/*" }), (req, res) => {
  const sig = req.headers["x-nexo-signature"] as string;
  if (!verifyWebhook(req.body.toString(), sig, process.env.PPOSTAL_WEBHOOK_SECRET!)) {
    return res.status(401).send("Invalid signature");
  }
  const event = JSON.parse(req.body.toString());
  console.log(event.event, event.message_id, event.state);
  res.sendStatus(200);
});

Retry schedule

Failed webhook deliveries are retried with exponential backoff: 1 min → 5 min → 30 min → 2 h → 12 h → 24 h. After 24 hours the dispatch is marked failed and no further retries occur.

Correspondence — topic threads

Correspondence gives your app persistent, encrypted conversation threads with a recipient, organized by topic — a business object of yours (a gig, an incident, a claim file). Postal Privado stores the thread (retained, encrypted at rest with per-recipient keys), delivers email nudges through the same pipeline as /v1/send, and keeps the evidence trail. The UI is yours: your operations inbox and your recipient portal render the thread; Postal Privado has no recipient-facing chat UI.

Create (or fetch) a conversation

Idempotent per (recipient, topic_ref): posting the same topic again returns the existing conversation (200 instead of 201). Omit topic_ref for the recipient's general thread. The recipient must have an email on file (422 recipient_no_email); a recipient who blocked you returns 403.

POST /api/v1/conversations
Authorization: Bearer <api_key>

{
  "recipient": { "email": "artist@example.com" },
  "topic_ref": "gig:268185",
  "topic_label": "Sala Apolo — 22 Aug"
}

// 201 Created (200 if it already existed)
{
  "conversation_id": "afac3c9b-…",
  "topic_ref": "gig:268185",
  "topic_label": "Sala Apolo — 22 Aug",
  "status": "open",
  "unread_from_app": 0,
  "unread_from_recipient": 0,
  "last_message_at": null,
  "recipient_portal_url": "https://postalprivado.com/p/mt_…"
}

Integration requirement: your thread UI must show a discreet notice — "Canal certificado por Postal Privado" — linked to recipient_portal_url, where the recipient manages their delivery preferences and can exercise their rights. It may be small; it may not be removed.

Post messages

Staff messages carry an author_label (the recipient sees people, not a company). With nudge.enabled, Postal Privado emails the full message to the recipient (subject to a per-conversation cooldown), with a CTA deep-linking into your portal — cta_url is optional: omit it and the CTA links to the recipient's hosted conversation page on postalprivado.com, so you can run conversations with no frontend of your own. The nudge is a regular send: it consumes your monthly quota and honors the recipient's SMS heads-up opt-in. Recipient messages are posted by your backend on behalf of your portal-authenticated user.

POST /api/v1/conversations/:id/messages
{ "body": "Confirmed for Saturday — bring the setlist.",
  "author_label": "Ops — Xarxa",
  "nudge": { "enabled": true, "cooldown_minutes": 15,
             "cta_url": "https://yourapp.com/c/<portal-token>" } }
             // cta_url optional — defaults to the hosted thread page
// → { "message_id": "…", "nudge_message_id": "…" }

POST /api/v1/conversations/:id/messages/recipient
{ "body": "Got it, see you there.",
  "reply_to_message_id": "0f544e7e-…" }   // optional quote anchor (both endpoints);
                                          // must reference a message in the same stream

GET /api/v1/conversations/:id/messages?since=<ISO>   // decrypted, for polling
GET /api/v1/conversations?since=&topic_ref=          // staff inbox in one poll

POST /api/v1/conversations/:id/read
{ "reader": "recipient", "up_to_message_id": "…" }   // fires conversation.message.read

Reading the thread

since is a strict cursor: pass the created_at of the last message you have and you receive only what came after it (ascending, max 500 per call). On the inbox list, since filters by last_message_at (max 200, most recent first). For /read: reader is who read — it marks the other side's messages as read up to (and including) up_to_message_id.

// GET /api/v1/conversations/:id/messages → 200
{
  "conversation_id": "afac3c9b-…",
  "messages": [
    { "message_id": "0f544e7e-…", "direction": "app",
      "author_label": "Ops — Xarxa",
      "body": "Confirmed for Saturday — bring the setlist.",
      "channel_origin": "web", "nudge_message_id": "93b78e8c-…",
      "created_at": "2026-07-11T05:17:07Z", "read_at": null },
    { "message_id": "a88cb5bf-…", "direction": "recipient",
      "author_label": null,
      "body": "Got it, see you there.",
      "channel_origin": "web", "nudge_message_id": null,
      "reply_to_message_id": "0f544e7e-…",   // render the quoted snippet from your copy
      "created_at": "2026-07-11T05:17:11Z", "read_at": null }
  ]
}

Webhooks

Two new event types arrive through your existing webhook endpoint, signed with the same HMAC scheme: conversation.message.received (the recipient wrote — what your staff inbox listens for) and conversation.message.read. Message bodies never travel in webhooks — fetch them via GET.

// POST to your webhook_url — headers:
//   X-Postalprivado-Signature: sha256=<hmac of the raw body>
//   X-Nexo-Signature: (legacy alias, same value)

{ "event": "conversation.message.received",
  "conversation_id": "afac3c9b-…",
  "topic_ref": "gig:268185",
  "timestamp": "2026-07-11T05:17:11Z",
  "message_id": "a88cb5bf-…",          // the conversation message to GET
  "channel_origin": "web",
  "reply_to_message_id": "0f544e7e-…" }  // null unless the reply quotes a message

{ "event": "conversation.message.read",
  "conversation_id": "afac3c9b-…",
  "topic_ref": "gig:268185",
  "timestamp": "2026-07-11T06:02:40Z",
  "up_to_message_id": "0f544e7e-…",
  "messages_read": 1 }

Rate limits, separate from your send quota: 10 messages/min per conversation, 60/min per app. Roadmap: recipients replying directly from their email client into the thread, and SMS/WhatsApp nudges on higher plans (always subject to the recipient's opt-in).

Widget embed (early access)

Embed the conversation thread directly in your own app as an iframe. Postal Privado hosts the UI: your customer reads and replies in place, replies land in the same canonical stream as the API, and you never handle their contact details. Available to KYC-verified apps.

1 — Issue a session (server-side)

Your backend exchanges its API key for a short-lived widget session. Never call this from the browser — the API key must stay on your server.

POST /api/v1/widget/sessions
Authorization: Bearer nexo_sk_YOUR_API_KEY

{ "recipient": { "email": "ana@example.com" },
  "topic_ref": "gig:268185",             // optional — scopes the thread to a topic
  "origin": "https://yourapp.com",       // the page that will embed the iframe
  "scope": "conversation" }              // or "inbox" for the multi-thread feed

// → 202
{ "session_token": "ws_…",
  "widget_url": "https://postalprivado.com/widget?s=ws_…",
  "scope": "conversation",
  "conversation_id": "afac3c9b-…",
  "expires_at": "2026-07-22T13:00:00Z" }  // sessions live 1 hour

2 — Embed the iframe

<iframe src="{widget_url}" style="width: 100%; height: 480px; border: 0;" />

The widget only loads inside the origin you declared when issuing the session — enforced with a frame-ancestors CSP header. An invalid or expired token serves frame-ancestors 'none', which the browser reports as a bare “refused to connect” inside the iframe. Request a fresh session on every page load— don't cache the token or the URL.

Scopes

conversation renders a single thread (resolved from topic_ref, creating the conversation if needed — same semantics as POST /v1/conversations). inbox renders every conversation between your app and that recipient, with unread badges.

What happens inside

Recipient replies (including quoted replies via reply_to_message_id) enter the canonical stream and fire conversation.message.received on your webhook, exactly like the recipient portal. Messages are marked read when they are actually on screen — the widget waits for the tab to be visible — and a read clears any pending email nudge for those messages. You don't poll anything: react to webhooks as usual.

Fair usage policy

Each plan has three layers of limits — a monthly cap, anti-burst rate limits, and per-channel sub-caps. Anti-burst limits are hard: exceeding them returns 429 Too Many Requests. Monthly caps are currently soft: sends past the cap keep working while we contact you about upgrading. Every response carries X-RateLimit-* headers indicating remaining quota.

Monthly caps (the "X messages/mo" advertised)

Per-channel sub-caps

SMS notices carry real per-message carrier costs, so each plan has a ceiling on them. Email volume is bounded only by the monthly total cap. WhatsApp delivery is not currently available (see note below).

Conversation recipients

Correspondence and the embeddable widget are included in every plan. What scales with the plan is how many distinct recipients your app can hold conversations with (one canonical stream per recipient):

The cap is enforced only when opening a conversation with a new recipient: the request returns 403 conversation_recipient_cap. Existing threads keep working and inbound replies are never blocked. Conversation messages themselves don't consume your monthly message cap — the email nudges they trigger do.

Anti-burst rate limits

These windows reset continuously (sliding window on created_at). They protect against accidental loops, not legitimate batch sends — if you consistently hit them, you should be on a higher plan.

Reading the response headers

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit-Hour: 500
X-RateLimit-Remaining-Hour: 487
X-RateLimit-Limit-Minute: 30
X-RateLimit-Remaining-Minute: 0

{
  "error": "Per-minute rate limit reached",
  "reason": "per_minute"
}

Best-effort delivery disclosure

Postal Privado sits on top of carriers (Resend for email, LabsMobile for SMS) whose delivery guarantees we inherit. Each delivery attempt receives exponential retries (1m → 5m → 30m → 2h → 12h → 24h) with dead-letter after 6 failures within 24 hours. Free / Starter / Pro plans carry no contractual SLA; SLA terms are available on Enterprise.

Changelog