STATXE Developers

Build with secure messaging, contacts, broadcasts, and automation APIs.

Create a key, validate it against /api/v1/me, copy a request, and move to production without waiting on support.

Open docs.statxe.comGet API keyDownload OpenAPI
Live
Use the REST API
Call inbox, outbox, contact, segment, and webhook endpoints from your backend.
Live
Receive Webhooks
Subscribe to contact, broadcast, email, and compliance events with signed delivery.
Portal only
Request assistant approval
Approved orgs get assistant recipes inside the authenticated portal, not the public docs.
Canonical
Public docs site
Guides, recipes, Scalar reference, and error catalog live at docs.statxe.com.
Visit docs
Developer docs sections
Getting Started
Start with the smallest working integration, then add production controls.
  1. 1. Create a scoped API key.

    Use the portal to create a stx_ key with only the scopes your integration needs.

  2. 2. Validate it with /api/v1/me.

    The response confirms org, key id, scopes, and rate-limit profile.

  3. 3. Make one read request.

    Start with contacts, inbox threads, broadcasts, or webhook delivery logs.

  4. 4. Add idempotent writes and webhooks.

    Use retry-safe writes and signed webhooks before going live.

Manage API keysOpen raw OpenAPI JSON
Authentication
Every public API call uses a bearer API key created for the public API audience.

Send the key in the Authorization header. Do not put keys in query strings, logs, or frontend bundles you do not control.

Public keys authorize only the versioned /api/v1 surface. They do not grant access to older portal routes or internal assistant systems.

Production key handling
Store keys server-side, rotate them during off-hours, and create separate keys for test, staging, and production jobs.
curl https://api.statxe.com/api/v1/me \
  -H "Authorization: Bearer stx_live_xxx"
Scopes
Filter the scope catalog and confirm the exact scope required by each endpoint.
me:readmereadpublic

Inspect the current API key, org, scopes, and rate-limit profile.

domains:readdomainsreadpublic

Read verified sending domains and available sender identities.

inbox.threads:readinboxreadpublic

Read inbox threads, messages, and delivery events.

inbox.threads:writeinboxwritepublic

Update inbox thread/message state such as read, starred, archived, and tags.

inbox.messages:sendinboxsendpublic

Send 1:1 conversation email from a mailbox you are assigned: new threads and replies, with the sender's signature. Uses no email credits; new threads count against the domain's daily limit, replies never do.

outbox.broadcasts:readoutboxreadpublic

Read outbox broadcasts, campaign drafts, schedules, and send status.

outbox.broadcasts:writeoutboxwritepublic

Create and update broadcast drafts and schedules.

outbox.broadcasts:sendoutboxsendpublic

Launch or cancel broadcast/send lifecycle operations.

outbox.transactional:sendoutboxsendpublic

Send individual transactional emails via the API or the SMTP front door. Deliberately separate from outbox.broadcasts:send so an SMTP-only key cannot launch a broadcast.

outbox.marketing:sendoutboxsendpublic

Send one marketing email to one contact (flow steps). Promotes the contact into a free premium slot, adds the legal footer and unsubscribe link, and queues the send when the domain is at its daily limit.

contacts:readcontactsreadpublic

Read contacts and contact metadata.

contacts:writecontactswritepublic

Create, update, import, export, and delete contacts.

segments:readsegmentsreadpublic

Read segments, groups, and membership lists.

segments:writesegmentswritepublic

Create/update segments and manage contact membership.

webhooks:readwebhooksreadpublic

Read webhook endpoints and delivery status.

webhooks:writewebhookswritepublic

Create and update webhook endpoints.

webhooks:adminwebhooksadminpublic

Delete webhooks, rotate secrets, and replay deliveries.

api_keys:readapi_keysreadpublic

Read API key metadata.

api_keys:writeapi_keyswritepublic

Create and revoke API keys.

automations:readautomationsreadpublic

Read automations and their run history.

automations:writeautomationswritepublic

Update an automation's name, description, and status (activate/pause/archive), and delete automations. Creating an automation's workflow is not yet supported over the API — use the dashboard.

templates:readtemplatesreadpublic

Read email templates.

templates:writetemplateswritepublic

Create, update, and delete email templates.

metrics:readmetricsreadpublic

Read send/engagement metrics summaries.

assistant.chat:writeassistantwritegated

Send gated assistant chat requests for admin-approved orgs.

assistant.tools:readassistantreadgated

Discover gated assistant tools available to an approved org.

assistant.sessions:readassistantreadgated

Read gated assistant session and usage state.

Endpoint scope map

GET/api/v1/me

Test an API key

me:read
GET/api/v1/contacts

List contacts

contacts:read
POST/api/v1/contactsIdempotent write

Create a contact

contacts:write
GET/api/v1/contacts/{id}

Retrieve a contact

contacts:read
PATCH/api/v1/contacts/{id}Idempotent write

Update a contact

contacts:write
DELETE/api/v1/contacts/{id}Idempotent write

Delete a contact

contacts:write
GET/api/v1/segments

List segments

segments:read
POST/api/v1/segmentsIdempotent write

Create a segment

segments:write
GET/api/v1/inbox/threads

List inbox threads

inbox.threads:read
GET/api/v1/outbox/broadcasts

List broadcasts

outbox.broadcasts:read
POST/api/v1/outbox/broadcastsIdempotent write

Draft a broadcast

outbox.broadcasts:write
GET/api/v1/webhooks

List webhook endpoints

webhooks:read
POST/api/v1/webhooksIdempotent write

Create a webhook endpoint

webhooks:write
GET/api/v1/webhooks/deliveries

List webhook delivery logs

webhooks:read
POST/api/v1/webhooks/deliveries/{id}/replayIdempotent write

Queue a webhook delivery replay

webhooks:admin
Errors
All errors use a stable envelope with a request id for debugging and support.
{
  "ok": false,
  "error": {
    "code": "missing_scope",
    "message": "The API key does not include the required scope.",
    "docs_url": "https://docs.statxe.com/api/errors/missing_scope"
  },
  "meta": {
    "request_id": "req_123"
  }
}
invalid_request

The request payload or query parameters are invalid.

invalid_api_key

The API key is missing, invalid, or expired.

missing_scope

The API key does not include the required scope.

not_found

The requested resource was not found.

conflict

The request conflicts with the current resource state.

rate_limited

The request exceeded the configured rate limit.

idempotency_conflict

The idempotency key was already used with a different request.

insufficient_credits

The workspace has no email credits left for this send.

webhook_signature_invalid

The webhook signature is missing, expired, or invalid.

internal_error

An unexpected server error occurred.

Rate Limits
Limits are enforced per API key with a minute window, burst capacity, and retry guidance.
Default floor

Keys get at least 60 requests per minute.

Burst

Burst capacity is included and capped to keep traffic fair.

429 recovery

Respect Retry-After and retry with backoff.

Use the playground’s GET /api/v1/me preset to inspect the current key’s meta.rate_limit profile.

Idempotency
Mutating requests are designed to be safely retried without creating duplicate work.

Send an Idempotency-Key header on every POST, PATCH, and DELETE. Keys must be 8 to 128 characters.

Reusing the same key with the same request replays the stored response. Reusing it with different request content returns idempotency_conflict.

Generate keys from your job id, import row id, or queue message id so retries preserve the same operation identity.
Inbox API
Read inbox threads for syncing support and message workflows.
GET/api/v1/inbox/threads

List inbox threads

inbox.threads:read
Outbox API
Read broadcasts, create drafts, and keep sending operations behind explicit scopes.
GET/api/v1/outbox/broadcasts

List broadcasts

outbox.broadcasts:read
POST/api/v1/outbox/broadcastsIdempotency-Key

Draft a broadcast

outbox.broadcasts:write
Contacts API
Create, update, list, and delete contacts with cursor pagination and retry-safe writes.
GET/api/v1/contacts

List contacts

contacts:read
POST/api/v1/contactsIdempotency-Key

Create a contact

contacts:write
GET/api/v1/contacts/{id}

Retrieve a contact

contacts:read
PATCH/api/v1/contacts/{id}Idempotency-Key

Update a contact

contacts:write
DELETE/api/v1/contacts/{id}Idempotency-Key

Delete a contact

contacts:write
Webhooks
Subscribe to signed delivery events, track attempts, and replay failed deliveries.
Verify the timestamped t=...,v1=... signature.
Return 2xx only after durable processing.
Use event ids to dedupe retries and replays.

Each delivery is an HTTPS POST of { id, type, created_at, data } with the headers statxe-signature, statxe-event-id, statxe-event-type and statxe-delivery-id. Answer within 10 seconds. Timeouts, 408, 409, 425, 429 and 5xx are retried after 1m, 5m, 15m, 1h and 6h; other answers, redirects included, are final until you replay them.

GET/api/v1/webhooks

List webhook endpoints

webhooks:read
POST/api/v1/webhooksIdempotency-Key

Create a webhook endpoint

webhooks:write
GET/api/v1/webhooks/deliveries

List webhook delivery logs

webhooks:read
POST/api/v1/webhooks/deliveries/{id}/replayIdempotency-Key

Queue a webhook delivery replay

webhooks:admin
import crypto from "node:crypto"

// statxe-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
// keyed with your endpoint's whsec_... secret, used as-is.
export async function POST(request: Request) {
  const body = await request.text() // the raw body, before any JSON parsing
  const header = request.headers.get("statxe-signature") ?? ""
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  const expected = crypto
    .createHmac("sha256", process.env.STATXE_WEBHOOK_SECRET!)
    .update(`${parts.t}.${body}`)
    .digest("hex")
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300
  const valid =
    fresh &&
    typeof parts.v1 === "string" &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  if (!valid) return new Response("invalid signature", { status: 400 })

  const event = JSON.parse(body) // { id, type, created_at, data }
  // event.id is the same on every retry and replay: process each id once.
  return new Response(null, { status: 204 })
}
Manage webhook endpoints
Assistant Access
Assistant APIs are gated and exposed inside the authenticated portal for approved orgs.

Assistant traffic must flow through the internal AI layer for policy, tool allowlists, usage budgets, audit logging, and provider abstraction before any broader external exposure.

If your org is approved, use the portal assistant experience instead of attempting direct public API calls.

Open Assistant