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:

# Por móvil (WhatsApp / SMS)
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": { "phone_e164": "+34600123456" },
    "envelope": {
      "subject": "Acceso a tu plataforma de formación",
      "body": "Hola, aquí tienes tu enlace de acceso: https://plataforma.example.com/login?token=abc123"
    }
  }'

# Por email
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"
    }
  }'

If this is the recipient's first message from you, Postal Privado will send them a consent request. If they have already accepted, the message is delivered directly.

POST /v1/send

Submit a message for delivery.

Request body

Response (202 Accepted)

{
  "message_id": "04b6bad3-6378-41cb-8a42-d41bf052d269",
  "state": "notified",            // or "accepted" if recipient already consented
  "expires_at": "2026-05-18T09:43:19.597+00:00",
  "consent_required": true,        // false once recipient has accepted
  "consent_request_id": "1a17fa2f-b95a-41f4-ab5d-089f36ffacbb"  // null when consent_required=false
}

Error responses

Message states

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

On reaching a terminal state, the encrypted envelope is purged from storage.

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": "whatsapp",
  "external_ref": null
}

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

Consent flow

Postal Privado is built around recipient consent. Here's how it works:

1. First contact: When you send to a recipient who has never accepted messages from your app, Postal Privado sends them a consent request via WhatsApp (or email as fallback). The response has state: "notified" and consent_required: true. The body of the original message is NOT shown to the recipient yet — only envelope.subject appears on the consent screen.
2. Recipient accepts: They tap the link in the consent message and confirm. State becomes accepted → delivering → delivered. You receive webhooks at each stage.
3. Future messages: Once a recipient has accepted from your app, subsequent sends return state: "accepted" immediately and skip the consent step.
4. Rejection: If the recipient rejects, state becomes rejected and future sends are blocked. They can re-enable from their recipient portal.
5. Anti-bombing: A recipient can have at most 3 pending consent requests at once. The 4th attempt returns HTTP 429 with state: "failed".

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": "whatsapp",
  "timestamp": "2026-05-11T09:44:02.118Z",
  "evidence_summary": { "type": "whatsapp_status", "provider": "meta" }
}

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.

Fair usage policy

Each plan has three layers of limits — a monthly cap, anti-burst rate limits, and per-channel sub-caps. When any limit is hit, requests return 429 Too Many Requests with X-RateLimit-* headers indicating remaining quota.

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

Per-channel sub-caps

WhatsApp and SMS carry real per-message carrier costs, so each plan has a hard ceiling on those channels. Email volume is bounded only by the monthly total cap.

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-Monthly: 5000
X-RateLimit-Remaining-Monthly: 0
X-RateLimit-Limit-Monthly-WhatsApp: 200
X-RateLimit-Remaining-Monthly-WhatsApp: 0
X-RateLimit-Limit-Hour: 500
X-RateLimit-Remaining-Hour: 487
X-RateLimit-Limit-Minute: 30
X-RateLimit-Remaining-Minute: 18

{
  "error": "Monthly message cap reached",
  "reason": "monthly_total"
}

Best-effort delivery disclosure

Postal Privado sits on top of carriers (Meta WhatsApp Cloud API, Twilio, Resend) 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.