Messaging API¶

The public REST API for sending messages and checking their status. Your backend calls it to send transactional and campaign messages to your customers — a welcome email, a password reset, a billing receipt, a campaign blast — and to ask, later, what happened to each one. It's the same surface our own SDKs are built on, so anything the Python client can do, you can do with a raw HTTP request.

This is the send-and-track half of Beacon. You hand us a recipient, a channel, and a template; we render it, send it through the right provider, and record the outcome as a delivery event. You learn the result one of two ways: poll GET /messages/{id}, or — better for anything at scale — subscribe to webhooks and let us push delivery outcomes to you. Most integrations do both: webhooks for the live signal, polling as a fallback and for reconciliation.

A quick map of where this fits before you dive in:

flowchart LR
  you[Your backend] -->|POST /messages| api[Messaging API]
  api --> ms[messaging-service]
  ms -->|render + send| prov[Email / SMS / Push provider]
  prov -->|outcome| ms
  ms -->|delivery event| mongo[(MongoDB)]
  ms -.->|webhook| you
  you -.->|GET /messages/id| api

The provider, the queueing, the retries, and the delivery log all live behind the API in messaging-service — you never touch them directly. You only ever see the two endpoints below and the webhooks.

Quickstart¶

Send a message, then read it back. These two calls cover the great majority of real usage.

# Send
curl -X POST https://api.beacon.example/messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Beacon-Version: 2026-05-01" \
  -H "Idempotency-Key: welcome-7a3f9c" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "channel": "email",
    "template": "welcome"
  }'

{
  "id": "msg_4Qk2...",
  "to": "user@example.com",
  "channel": "email",
  "status": "queued",
  "created": "2026-06-14T18:03:11Z"
}

The status you get back is almost always queued — the send is accepted and handed off, not yet delivered. To find out how it actually went, read it back by id:

# Check status
curl https://api.beacon.example/messages/msg_4Qk2... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Beacon-Version: 2026-05-01"

{
  "id": "msg_4Qk2...",
  "to": "user@example.com",
  "channel": "email",
  "status": "delivered",
  "created": "2026-06-14T18:03:11Z"
}

Delivery is asynchronous and can take a while — a provider may confirm seconds or minutes later, and some channels are slower than others. Don't busy-poll waiting for delivered; subscribe to webhooks instead and treat polling as a backstop.

Basics¶

• Base URL / environments — https://api.beacon.example (prod), https://api.sandbox.beacon.example (sandbox). Sandbox accepts the same calls but doesn't send real messages — use it to wire up your integration and exercise webhooks without emailing real people. Keys are environment-scoped (sk_live_… vs sk_test_…), so a sandbox key against the prod URL simply fails auth.
• Auth — bearer API key in Authorization: Bearer <key>, scoped per environment. Sending needs the messages:send scope; reading status needs messages:read. Full details, scopes, and key handling on the Auth page.
• Versioning — date-pinned via the Beacon-Version header (e.g. 2026-05-01). Breaking changes ship under a new date; old versions keep working for 12 months after a newer one lands. Pin a version explicitly in production so a future breaking change can't surprise you — omitting the header falls back to your account's default, which can move.
• Content type — request and response bodies are JSON (application/json). Timestamps are ISO-8601 UTC (created is date-time, read-only).
• Errors — JSON {code, message}; 429 carries a Retry-After. See Errors below.

Reference¶

The authoritative endpoint reference is rendered from the OpenAPI spec, compiled from the TypeSpec contracts in contracts/public-api/. The spec — not this page — is ground truth for exact field names, types, and required/optional status; the prose here exists to give you the why and the gotchas around it.

Endpoints at a glance¶

That's the whole public surface today — two endpoints. Everything else (templates, scheduling internals, the delivery-event log) is owned and managed inside messaging-service and isn't exposed here.

Sending a message¶

POST /messages takes three required fields and one optional one:

You always send a template name, never raw message bodies — Beacon renders the template on its side. That's deliberate: it keeps content, localization, and compliance (unsubscribe footers, etc.) in one place rather than scattered across every caller.

Message status¶

A message moves through these states. The set is fixed by the spec (MessageStatus):

stateDiagram-v2
  [*] --> queued
  queued --> sent
  sent --> delivered
  sent --> failed
  sent --> bounced
  delivered --> [*]
  failed --> [*]
  bounced --> [*]

The three terminal states map exactly to the outcomes recorded on a delivery event (delivered / failed / bounced) and to the webhook events of the same names. queued and sent are in-flight stages you'll see while polling but never as a final answer.

Errors¶

Errors come back as JSON with a stable machine-readable code and a human message:

{ "code": "invalid_request", "message": "Field 'template' is required." }

Branch on code, not on message (the wording can change). The usual HTTP conventions apply:

Guides¶

• Authentication — API keys, scopes, environments, key handling.
• Webhooks — get delivery outcomes pushed to you instead of polling. The recommended way to learn results at scale.
• Python SDK — the official client, with retries and pagination built in.

How the pieces fit together¶

This API is one of three customer-facing surfaces on the messaging domain, and they solve different problems — reach for the right one:

A typical lifecycle threads through all of them: authenticate with a key (Auth) → POST /messages here → receive a webhook when the outcome lands → optionally GET /messages/{id} to reconcile.

Notes & nuances¶