v1.0.0
OAS 3.1.0

Blocx API

Blocx is the multi-channel transactional API for product teams that need email, SMS/MMS, Telegram, and 2FA verification from a single provider — one bill, one SDK, one webhook contract.

Base URL

All API requests are made to:

https://api.otterblocx.com

Every path in this reference is relative to that base URL (e.g. POST /messages → https://api.otterblocx.com/messages). The 2FA verification endpoints (POST /verifications, POST /verifications/:id/check) are served by a separate service with its own base URL in production — see 2FA Verification Service.

Why Blocx

  • One API, every channel a real product needs. Transactional email, marketing email, SMS, MMS, Telegram, and 2FA verification through the same authentication, SDK, and signed webhook envelope. No second integration when you outgrow email-only — and no second integration ever for OTP/2FA over SMS or Telegram.
  • 2FA verification as a first-class service. Multi-channel verifications (EMAIL, SMS, TELEGRAM) with template approval, per-channel sender selection, and pay-on-delivery billing for Telegram. Drop-in replacement for hand-rolled OTP pipelines built on top of a generic email or SMS API.
  • Carrier-registered SMS, included. 10DLC brand registration, campaign registration, and downstream carrier sharing are first-class API resources — register and start sending without a side contract or third-party compliance vendor.
  • Receive, not just send. Inbound email with parsed MIME, SPF/DKIM/DMARC/spam/virus verdicts, presigned S3 attachment URLs, and a dedicated mailbox per address. Inbound SMS/MMS on every provisioned number. Both arrive through the same signed webhook contract you already wired up for outbound events.
  • Deliverability you can audit. Per-domain DKIM/SPF/DMARC setup, dedicated IP option on paid plans, open/click tracking opt-in per identity, and a full event stream (email.delivered, email.bounced, email.complained, email.opened, email.clicked) — so reputation problems are observable on day one, not after the first deliverability incident.
  • Predictable pricing. Each plan includes a monthly allowance per metered metric; overage is charged at the standard rate from a top-up balance. No per-channel minimums, no SMS short-code surcharges hidden in a separate invoice.

When to choose Blocx

Use case Surface
Transactional email for Supabase Auth / Auth.js / Clerk / custom auth POST /email with a verified EmailIdentity
OTP / 2FA over email, SMS, or Telegram POST /verifications → POST /verifications/:id/check
Application notifications (receipts, alerts, order updates) POST /email or POST /messages
Marketing email campaigns with templates POST /email + marketing_email capability
10DLC SMS at scale POST /brands → POST /campaigns → POST /messages
Inbound email parsing (support inboxes, reply-to workflows) Configure a mailbox; subscribe to email.received
MMS image / media delivery POST /messages with media URLs
Telegram channel posts and bot inbox replies POST /telegram/messages with a connected chat ID

If your stack is "transactional email only, forever," a single-channel provider is a fine choice. Pick Blocx when you ever expect to need SMS, 2FA, MMS, Telegram, or inbound parsing alongside email — integrating two vendors costs more in code, billing, and on-call surface than the per-message price difference.

Official SDK

Prefer a typed SDK over raw HTTP? Install @otterlabs/blocx — fully generated from this spec.

npm install @otterlabs/blocx
import { createBlocxClient, Messaging } from '@otterlabs/blocx'

const { client } = createBlocxClient({
  accessKeyId: process.env.BLOCX_ACCESS_KEY_ID!,
  secretAccessKey: process.env.BLOCX_SECRET_ACCESS_KEY!,
})

await Messaging.sendMessage({
  client,
  body: { to: '+15551234567', from: '+15559876543', body: 'Hello!', type: 'SMS' },
})

Help & guides

Step-by-step guides for everything you can do in Blocx — onboarding, brand and campaign registration, sending email, configuring webhooks, billing, and more — live in two places:

  • help.otterblocx.com — the human-friendly help center with full styling, search, and navigation.
  • api.otterblocx.com/articles — the same articles served as plain, chrome-free HTML directly off the API. This is the recommended index for AI agents and tooling that want to ingest the guides programmatically without parsing a marketing site.

Both surfaces serve identical content; pick whichever is easier for your reader.

Authentication

All requests require two headers:

  • x-access-key-id — Your API key ID
  • x-secret-access-key — Your API secret

Create API keys in the dashboard under Developer > API Keys.

Permissions

API keys carry scoped permissions. Each endpoint requires specific permissions (documented per endpoint). If a permission is missing, the request returns 403.

Available resources include messages, calls, email, campaigns, brands, numbers, messaging_profiles, webhooks, twofa, twofa_templates, telegram, integrations, quotas, api_logs, and team.

Call Control

Use PUT /phone-numbers/{id}/calling with {"enabled":true} to enable programmable calling on an owned number. Disable call forwarding and end live calls before changing its mode. Calling requires an active plan or trial, approved identity verification, the account's sms capability, a configured calling rate and sufficient balance where prepaid billing applies.

Endpoint Purpose Permission
PUT /phone-numbers/{id}/calling Enable or disable programmable calling numbers.write
POST /calls Dial from your number calls.write
GET /calls List history with status, number and pagination filters calls.read
GET /calls/{id} Retrieve current call state and usage calls.read
POST /calls/{id}/actions Answer, hang up, bridge, speak text or send keypad digits calls.write

Dial requests require a UUID requestId, numeric phoneNumberId and E.164 to destination. Commands require a UUID commandId and an action. Save each UUID and body before submitting, then reuse both after an interrupted response. Calling uses these JSON fields for retry safety; it does not use the messaging Idempotency-Key header. A recorded ID reused with different parameters returns 409.

Calls return a Blocx UUID in id. Command receipts can be accepted, pending or failed; acceptance is asynchronous. Subscribe to call.initiated, call.answered, call.ended, call.bridged, call.speech-ended and call.digits-received for progress. Calls must be active before speech, digits or bridging. Speech supports plain text in US English; a bridge connects two active calls in your account.

Each answered leg is billed per started minute at its captured rate. Amounts are microdollar strings, and usage may remain unsettled until delayed lifecycle information arrives. See the Call Control API guide for complete examples, receipts, signed event payloads, limits and error handling, or Programmable Calling for dashboard instructions.

Telegram bots

Open Developer → Telegram → Bot setup in the dashboard. Choose Use the Blocx bot for channel posts, or Bring your own bot for channels and a private customer inbox. Telegram Gateway OTPs remain under 2FA and do not use these bots.

For the shared bot, create a one-time link with POST /telegram/link, open its deepLink, and press Start in Telegram. Links expire after ten minutes and can only be used once. Add the bot as a channel administrator with posting rights using that linked Telegram account. If the bot was already present before linking, remove and add it again to trigger discovery.

For your own bot, create it through @BotFather and submit its token to POST /telegram/bot. Blocx encrypts the token and registers a secret-authenticated webhook. A bot already used by another service must be disconnected there first. Customers must start a private conversation with the bot before you can reply. Both the shared bot and your own bot capture new posts in connected channels. Your own bot also captures private messages. Incoming text and captions are saved; other attachments appear as a placeholder and must be viewed in Telegram. Past history, edits, deletions, group messages and linked discussion-group comments are not imported.

  • Read bot status with GET /telegram/connection; list channels with GET /telegram/chats?type=channels and private chats with ?type=inbox.
  • Send text or an HTTPS photo URL with POST /telegram/messages: { "chatId": "<Blocx chat UUID>", "text": "Hello" }. Text is limited to 4,096 characters, photo captions to 1,024. Supply a unique Idempotency-Key for each intentional send and reuse that key and body on retries.
  • HTTP 201 / sent means Telegram accepted the message, not that anyone read it. It is charged once at the account's Telegram outbound message rate. HTTP 422 / failed means rejected and is not charged. HTTP 202 / unknown is unconfirmed and is not charged; inspect Telegram before intentionally sending again. Retrying the same key never sends again.
  • Read history with GET /telegram/chats/:id/messages and an individual outcome with GET /telegram/messages/:id. Follow nextCursor using before for additional pages.
  • Subscribe to telegram.sent, telegram.received, telegram.failed, and telegram.unknown through the standard customer webhooks. Deduplicate retries using the stable event ID.
  • PATCH /telegram/chats/:id with { "enabled": false } disconnects a chat. Re-enable after restoring Telegram permissions. DELETE /telegram/bot disconnects your bot; DELETE /telegram/link removes linked accounts and disables shared-bot sending and capture. History remains available.

Reading chats requires telegram.read; posting requires telegram.send, the telegram capability, an eligible paid account, verified identity, and sufficient balance. Connection changes require integrations.write; connection status requires integrations.read. Default send limits are 60 per account and 20 per chat per minute, with Telegram's own limits also applying.

Send through the shared bot

After linking and adding the bot as an administrator, call GET /telegram/chats?type=channels and use the returned id (a Blocx UUID, not the numeric Telegram chatId):

curl https://api.otterblocx.com/telegram/messages \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: announcement-001' \
  -d '{"chatId":"a55beea8-7152-429e-8b13-ff17bfacdc24","text":"Hello everyone!"}'

The chat determines which bot sends the message; no bot token is needed in this request. Reuse announcement-001 with the identical request on a retry, and use a fresh key for a different intentional message.

Receive channel posts and private messages

Blocx registers Telegram callbacks automatically. New posts in an enabled, connected channel appear in that channel's message history for both the shared bot and your own bot. Private messages to your own bot appear in the Inbox. Both publish telegram.received through the same customer webhook delivery queue used for SMS and email, with the Blocx chat UUID in data.chatId. Incoming posts are not charged. Shared channels must first be discovered when a linked account adds the bot; a post alone cannot claim a shared channel for a workspace. Disabling the chat or removing the bot stops capture.

Register your application endpoint through POST /webhooks with webhooks.write permission:

{
  "url": "https://your-app.example/webhooks/blocx",
  "eventTypes": ["telegram.received", "telegram.sent", "telegram.failed", "telegram.unknown"]
}

Save the signing secret returned at creation. You can also add these event types to an existing webhook through PATCH /webhooks/{publicId}. Verify Blocx-Signature using the standard webhook procedure below, deduplicate by the envelope id, and acknowledge promptly with a 2xx response. The normal retry schedule and webhook delivery logs apply. Repeated Telegram updates do not create duplicate inbox messages; customer webhook delivery remains at least once.

Reply using POST /telegram/messages with the incoming event's data.chatId and a new idempotency key. Use GET /telegram/chats?type=inbox to look up the customer's name, Telegram username, and numeric chat ID. Edits, deletions, group messages, and past Telegram history are not imported; incoming private text and captions are supported, and other attachments appear as a placeholder.

Rate Limits & Quotas

Rate limits are enforced per-account and, where applicable, per-recipient. Default limits are applied to all accounts. Custom limits can be requested via the Quotas API or the dashboard.

Rate limit headers on applicable endpoints: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Idempotency Keys

Use the optional Idempotency-Key header on POST /messaging/send to retry an SMS or MMS submission without creating another message. This also applies to sandbox sends. Email and 2FA verification endpoints do not currently implement this header.

Create a key once per logical message and recipient, save it with your sending job and request body, and reuse both on every retry. A UUID or a stable event-and-recipient identifier works well. Generate a new key for each intentional new message, even when its content is identical.

curl -i https://api.otterblocx.com/messaging/send \
  -H "x-access-key-id: $BLOCX_ACCESS_KEY_ID" \
  -H "x-secret-access-key: $BLOCX_SECRET_ACCESS_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-dispatched-recipient-17' \
  -d '{"from":"+15551234567","to":"+15557654321","body":"Your order has shipped.","type":"SMS"}'

If this request times out, repeat it with the same key and body. Replace the example key when sending a different logical message.

Key rules and replay behavior

  • Keys are case-sensitive and must contain 1–128 printable ASCII characters without spaces (! through ~).
  • Keys are scoped to your account, so API keys belonging to the same account share the same idempotency namespace.
  • The key binds the validated message body, including sender, recipient, message type, text, media URLs, and tags. Changing these under an existing key returns 409 idempotency_conflict. JSON whitespace and object property order do not matter; omitted defaults such as type: "SMS" are normalized.
  • Records are retained for at least 90 days from the first request. Retries do not restart that period. Do not reuse old keys or rely on deduplication after that window.
  • A completed request replays its original HTTP status and response body, with Idempotency-Replayed: true and the same X-Message-Id. Each HTTP attempt has its own X-Request-Id. Replaying does not create another message or reserve funds or consume sending quotas again.
  • Requests without a key are independent sends, including requests with identical content. Adding a key after an unkeyed timeout cannot recover or deduplicate that earlier request.

Handling responses

Response What to do
202 Accepted Save messageId and stop submitting that message. Acceptance is asynchronous; follow delivery through history or webhooks. A replay still returns the original acceptance even if processing has since finished.
400 invalid_idempotency_key Correct the key format. No send was started by this request.
409 idempotency_conflict The key already belongs to different content. Recover the original body for a retry; use a new key only for an intentional separate message.
409 idempotency_in_progress Another request with this key is still preparing. Wait for Retry-After seconds, then retry the same key and body.
503 send_outcome_unknown, timeout, or connection loss The send may have been accepted. Retry with the same key and body, or look up the message. Never switch to a new key or omit the header to bypass uncertainty.
409 send_outcome_unknown Preparation was interrupted and cannot be recovered automatically. Contact support with messageId and X-Request-Id; do not create a replacement send.
Completed preflight rejection, such as 402 or 429 The rejection is replayed, even after balance or rate limits recover. Fix the cause and use a new key for the corrected attempt only when the rejection is definitive.

Authentication and request-body validation run before a key is claimed; their failures are not saved as keyed responses. Do not treat an arbitrary 5xx as proof that nothing was sent.

Check a saved message with GET /messaging/sends/{messageId}, using the same authentication headers and the messages.send permission. This reports submission/processing state, not handset delivery: SENT means provider acceptance, while UNKNOWN requires investigation and blocks automatic resend. A 404 does not prove that the original send failed. Keep the original key, body, message ID, and request IDs for reconciliation.

Usage Reports (MDR)

Message Detail Record (MDR) endpoints break your SMS/MMS traffic and spend down per phone number, computed on demand from message history. Both require the messages.read permission and the sms capability.

  • GET /reports/usage — usage aggregated per phone number over a date range: outbound/inbound counts, segments, delivered/failed, and cost.
  • GET /reports/messages — the underlying detail records, one row per message, with per-message segments, status, price code, and cost. JSON responses are cursor-paginated via nextToken.

Date range. Pass start and end as either a calendar day (YYYY-MM-DD) or a full ISO 8601 timestamp. The range defaults to the trailing 30 days and is capped at 92 days; a wider request is clamped, and the applied range is echoed back in range.

Cost fields. All amounts are in microdollars (1 USD = 1,000,000 µ$), returned as strings to preserve precision. Cost is split so each component reconciles independently:

  • costMicros — per-segment message charges.
  • carrierCostMicros — carrier pass-through surcharges, recorded on the terminal delivery webhook.
  • totalCostMicros — the sum of the two.

Filters. Narrow either report with phoneNumber (a single owned E.164 number) and direction (OUTBOUND or INBOUND). /reports/messages additionally accepts from, to, status, and tag — use from/to for the most efficient per-number drill-down.

CSV export. Add format=csv to either endpoint for a spreadsheet-ready download (Content-Type: text/csv). CSV exports cover the full range; the X-Report-Truncated response header is true if the export hit the scan safety cap, in which case narrow the range and export in slices.

Carrier surcharges are attributed per number only for messages finalized after this feature shipped; older records report 0 carrier cost (the per-segment charge is unaffected).

Test Phone Sandbox

Every account can send outbound SMS from a shared test phone number without registering a 10DLC brand, getting a campaign approved, or buying a number. It's intended for first-call integration testing and webhook wire-up.

The shared test number is +13079999302 (same for every account).

To use it, set from to +13079999302 when calling POST /messaging/send. Test sends are subject to four rules:

  • [Otter] prefix. The body must start with [Otter]. Otherwise the request returns 400 with code: "test_prefix_required".
  • Heavy rate limit. Default caps are 5/min, 30/hour, 100/day per account. Exceeding any window returns 429 with code: "test_rate_limited". These caps cannot be raised — graduate to a real number when you outgrow them.
  • Outbound only. Replies to the test phone are dropped; message.received is never fired. Provision a real number if you need inbound.
  • No billing. Test sends do not draw from your balance and are not counted toward your monthly included quota.

Test sends flow through the same queue, carrier, webhook contract, and event types as real sends — message.sent, message.delivered, and message.failed all fire normally — so your integration code does not need to special-case them. The send response includes "test": true for client-side disambiguation.

2FA Verification Service

The 2FA verification endpoints (POST /verifications, POST /verifications/:id/check) are served by a separate service. In production, use the 2FA service base URL. Templates are managed through this API under /twofa/templates.

Channels: Verifications support EMAIL, SMS, and TELEGRAM. Set channel on the request and provide a matching to (email address or E.164 phone). Each channel supports its own template type and an optional tenant-owned sender:

  • EMAIL — fromIdentityId selects a verified EmailIdentity. Omit it to send from the system default sender.
  • SMS — fromPhoneNumberId selects a tenant phone number that is ASSIGNED/ACTIVE and attached to a messaging profile. Omit it to send from the system verification short code 436961, which supports US recipients.
  • TELEGRAM — Delivered via Telegram Gateway to the recipient's Telegram account on the given E.164 phone number. The message body is formatted by Telegram and cannot be customized — templateId and sender overrides are not supported. Returns 422 if the recipient is not reachable on Telegram (no Telegram account, or messaging the sender is restricted). Billed only after delivery is confirmed by the Gateway.

Template approval: New templates are auto-approved on create and on edit, so they're usable immediately. A template's channel must match the verification request's channel. SMS templates additionally require a tenant-owned fromPhoneNumberId — they cannot be sent from the system default number.

Webhooks

Subscribe to events that happen in your account by registering one or more webhook endpoints under /webhooks. We POST a signed JSON body to your URL whenever a subscribed event fires.

Event types

Event Fires when
message.sent An outbound SMS/MMS has been accepted by the carrier
message.delivered An outbound SMS/MMS was delivered to the handset
message.failed An outbound SMS/MMS could not be delivered
message.received An inbound SMS/MMS arrived on one of your numbers
telegram.received A new connected-channel post or private message to your own bot
telegram.sent Telegram accepted an outbound bot message
telegram.failed Telegram explicitly rejected an outbound bot message
telegram.unknown Delivery could not be confirmed; check Telegram before creating another send
email.delivered An outbound email was accepted by the recipient mail server
email.bounced An outbound email bounced
email.complained A recipient marked your message as spam
email.opened A recipient opened the email (if open tracking is enabled)
email.clicked A recipient clicked a tracked link
email.received An inbound email arrived on one of your mailboxes

Payload envelope

Every delivery has the same outer shape. Upstream carrier and mail-provider differences are normalized by Blocx before dispatch — your handler does not need to branch on which underlying provider produced the event. Any provider field in the payload is an opaque internal identifier and should not be parsed or depended on by integrations.

{
  "id": "evt_8f2a4d6e9c1b0a7d5e3f2c1b",
  "type": "message.delivered",
  "createdAt": "2026-05-06T12:34:56.789Z",
  "data": { /* event-specific, see below */ }
}

Event payloads (data field)

telegram.received / telegram.sent / telegram.failed / telegram.unknown

All Telegram events carry the message shape returned by the Telegram API. A full incoming-event envelope looks like:

{
  "id": "evt_tg_1937dbe5-0287-4efe-96cb-8a9f2994b323",
  "type": "telegram.received",
  "createdAt": "2026-11-19T10:00:00.000Z",
  "data": {
    "id": "1937dbe5-0287-4efe-96cb-8a9f2994b323",
    "chatId": "a55beea8-7152-429e-8b13-ff17bfacdc24",
    "direction": "inbound",
    "text": "Hello, when do you open?",
    "photoUrl": null,
    "status": "received",
    "error": null,
    "providerMessageId": "42",
    "amountMicros": "0",
    "createdAt": "2026-11-19T10:00:00.000Z"
  }
}

Outbound events have direction: "outbound" and status sent, failed, or unknown. amountMicros is a price snapshot, not proof of a charge; only accepted outbound sends are charged. data.chatId is the Blocx UUID for replying or reading history, and providerMessageId may be null for unsuccessful or unconfirmed sends.

message.sent / message.delivered

Delivery status update for an outbound SMS/MMS.

{
  "messageId": "msg_1717689296000",
  "providerMessageId": "40a8b6e7-...",
  "status": "DELIVERED",
  "from": "+15559876543",
  "to": "+15551234567",
  "direction": "OUTBOUND",
  "type": "SMS",
  "occurredAt": "2026-05-06T12:34:55.120Z"
}

message.failed

Same shape as above, with two additional fields describing the failure.

{
  "messageId": "msg_1717689296000",
  "providerMessageId": "40a8b6e7-...",
  "status": "FAILED",
  "from": "+15559876543",
  "to": "+15551234567",
  "direction": "OUTBOUND",
  "type": "SMS",
  "occurredAt": "2026-05-06T12:34:55.120Z",
  "errorCode": "40010",
  "errorMessage": "Destination unreachable"
}

message.received

An inbound SMS/MMS arrived on one of your numbers.

{
  "messageId": "msg_in_01HK9...",
  "providerMessageId": "40a8b6e7-...",
  "from": "+15551234567",
  "to": "+15559876543",
  "direction": "INBOUND",
  "type": "SMS",
  "text": "Hello!",
  "media": [
    { "url": "https://...", "contentType": "image/jpeg" }
  ],
  "occurredAt": "2026-05-06T12:34:55.120Z"
}

email.delivered / email.bounced / email.complained

Status update for an outbound email. bounceType/bounceSubType are present on email.bounced; complainedAt is present on email.complained.

{
  "messageId": "eml_1717689296000",
  "status": "DELIVERED",
  "from": "hello@example.com",
  "to": ["user@recipient.com"],
  "subject": "Welcome aboard",
  "domain": "example.com",
  "occurredAt": "2026-05-06T12:34:55.120Z"
}

email.bounced adds:

{
  "bounceType": "Permanent",
  "bounceSubType": "General",
  "diagnosticCode": "smtp; 550 5.1.1 user unknown"
}

email.opened / email.clicked

Engagement events (only fire if open/click tracking is enabled on the identity).

{
  "messageId": "eml_1717689296000",
  "to": "user@recipient.com",
  "userAgent": "Mozilla/5.0 ...",
  "ipAddress": "203.0.113.42",
  "occurredAt": "2026-05-06T12:35:30.000Z",
  "link": "https://example.com/landing"
}

link is only present on email.clicked.

email.received

An inbound email arrived on one of your mailboxes. The message body is not included in the webhook payload — only metadata, headers, and attachment metadata. Fetch the raw MIME from S3 (or via the dashboard) when needed.

{
  "messageId": "abc123def456...",
  "receivedAt": "2026-05-06T12:34:56.789Z",
  "from": [
    { "name": "Jane Doe", "address": "jane@sender.com" }
  ],
  "to": [
    { "name": null, "address": "k7q9...@inbound.otterblocx.com" }
  ],
  "cc": [],
  "subject": "Re: your invoice",
  "text": "Thanks — see attached.",
  "html": "<p>Thanks — see attached.</p>",
  "headers": {
    "Message-ID": "<...>",
    "Date": "Tue, 06 May 2026 12:34:55 +0000"
  },
  "spam": false,
  "verdicts": {
    "spam": "PASS",
    "virus": "PASS",
    "spf": "PASS",
    "dkim": "PASS",
    "dmarc": "PASS"
  },
  "attachments": [
    {
      "filename": "invoice.pdf",
      "contentType": "application/pdf",
      "size": 48211,
      "contentId": null,
      "url": "https://s3...presigned"
    }
  ],
  "mailbox": {
    "id": 42,
    "address": "k7q9...@inbound.otterblocx.com",
    "label": "Support inbox"
  }
}

Attachment urls are presigned S3 URLs. They are time-limited (24h by default) — download or re-host within that window.

Verifying signatures

Each request carries these headers:

  • Blocx-Signature — t=<unix>,v1=<hex> where v1 is HMAC-SHA256(signingSecret, t + "." + rawBody).
  • Blocx-Timestamp — the same Unix timestamp as in the signature header (convenience copy).
  • Blocx-Event — the event type, e.g. message.delivered.
  • Blocx-Event-Id — stable event ID for idempotent processing.
  • Blocx-Attempt — current delivery attempt number (1-based).

Verification recipe (Node.js):

import { createHmac, timingSafeEqual } from 'crypto'

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  const t = Number(parts.t), v1 = parts.v1
  if (!t || !v1) return false
  if (Math.abs(Date.now() / 1000 - t) > 300) return false  // 5-minute tolerance
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
}

You must verify against the raw, unparsed request body. JSON re-serialization changes byte-for-byte content and will break the signature.

Retries

Failed deliveries (non-2xx response, network error, or timeout) are retried up to 5 attempts total with the following backoff:

Attempt Delay before this attempt
1 — (immediate)
2 30 seconds
3 2 minutes
4 5 minutes
5 15 minutes

After the 5th failure the delivery is recorded as FAILED and not retried further. Each request times out after 10 seconds.

Endpoint requirements

  • HTTPS only (HTTP is allowed in development).
  • The hostname must resolve to a public IP address. Private/loopback/link-local ranges (RFC1918, 169.254.0.0/16, 127.0.0.0/8, fc00::/7, etc.) are rejected at registration time and re-checked at delivery time to defeat DNS rebinding.
  • Respond with any 2xx status code within 10 seconds. The response body is captured (truncated to 2KB) for diagnostics.

Webhook deduplication

The same event may be re-delivered after a transient failure. Use Blocx-Event-Id to deduplicate.

API Request Logs

Every request you make with an API key is recorded and kept for 30 days: method, path, status, latency, and the request and response headers and bodies. Credentials are redacted (x-secret-access-key, Authorization, and body fields such as password, token, or a 2FA code show as [REDACTED]), and bodies over 32 KiB are truncated with the original size recorded.

Every response carries an X-Request-Id header. Quote it when contacting support, or fetch the full record with GET /api-logs/{requestId}. Browse and filter the log with GET /api-logs, or in the dashboard under Developer > API Logs.

Failed authentication attempts (an expired key or wrong secret) are attributed to the key's account by its access key id, so they appear in your log too. Requests to /api-logs itself are not logged.

Email Deliverability & Sender Authentication

Email reputation is enforced at the EmailIdentity level (one identity per sending domain or address). Every identity must complete sender authentication before it can send:

  • SPF — published as part of the domain record set returned by GET /email/identities/{id}. Required for all sending domains.
  • DKIM — Blocx generates a 2048-bit DKIM keypair per identity; the public key is exposed in the dnsRecords array on the identity. Required for all sending domains; rotated on request.
  • DMARC — Blocx surfaces a recommended DMARC record on each identity. Enforcement policy is left to the domain owner.
  • MX (inbound) — required only when the identity is configured to receive mail. Inbound identities are validated against the same SPF/DKIM/DMARC results before email.received is dispatched.

The full required record set for any identity is available at GET /email/identities/{id} under dnsRecords. Each record reports current verification state (PENDING, VERIFIED, FAILED) so that integrations can show setup status to end users.

IP reputation

Default sending is on a shared, warmed pool segmented by traffic class (transactional vs. marketing). Scale and Volume accounts can request a dedicated IP for marketing or high-volume transactional traffic — Blocx handles warming and reputation monitoring automatically.

Bounce, complaint, and engagement tracking

Per-identity event history is available through the webhook stream (email.delivered, email.bounced, email.complained, email.opened, email.clicked) and as paginated history under the identity resource. Bounce classification (Permanent / Transient / subtype) is normalized regardless of underlying upstream so deliverability dashboards do not need provider-specific parsing.

Suppression list

Hard bounces and recipient complaints are automatically added to a per-tenant suppression list. Attempts to send to a suppressed address return 409 SUPPRESSED without consuming quota or producing a webhook event. Suppression entries can be inspected and (where compliant) removed via the dashboard.

Attachments

POST /email/send accepts an attachments array. Rather than base64-encoding files into the request body, you pass a publicly reachable HTTPS URL for each file and Blocx downloads it at send time:

{
  "from": "billing@example.com",
  "to": ["customer@acme.com"],
  "subject": "Your invoice",
  "body": { "type": "HTML", "content": "<p>Invoice attached.</p>" },
  "attachments": [
    { "url": "https://cdn.example.com/invoices/INV-1042.pdf", "filename": "invoice.pdf" }
  ]
}
  • Limits. Up to 10 files and 25 MB total (decoded) per message — the ceiling SES allows once the files are MIME-encoded alongside the body.
  • filename / contentType are optional. When omitted, Blocx uses the response Content-Disposition and Content-Type, falling back to the URL basename and application/octet-stream.
  • URLs must be public. URLs that resolve to private, loopback, or link-local addresses are rejected, and the resolved IP is re-checked at fetch time to defeat DNS rebinding. Redirects are followed (up to 3 hops) and each hop is re-validated.
  • All-or-nothing. If any attachment cannot be fetched the send fails and no email is delivered: 400 with code attachment_blocked or attachment_fetch_failed, or 413 with attachment_too_large when the combined size exceeds the limit.

Async Operations

Brand registration, campaign creation, and domain setup are processed asynchronously. The API returns immediately with PENDING_REGISTRATION or PENDING status. Poll the resource to check completion.

Plans & Capabilities

Every account is on one subscription plan. New accounts choose from Starter, Scale, and Volume. Existing Free and Pay-as-you-go accounts keep their original rates, quotas, and capabilities. Scale and Volume are set up by our sales team at contract sign — the tenant-facing subscription endpoint refuses to switch onto them (403 CONTACT_SALES_REQUIRED) unless the request carries a Stripe promotion code whose coupon is restricted to that plan's product (e.g. BLOCX1001, which unlocks Scale at a $100 monthly minimum). Plans gate three things:

  1. Capabilities — boolean feature flags that decide which endpoints the tenant can call.
  2. Included quotas — a monthly allowance of metered usage per metric. Once exhausted, additional usage is charged from the account balance at the standard PriceItem rate.
  3. Spend cap and coverage — Starter and legacy Pay-as-you-go cap spend at $2,500/month and rejects non-US destinations. Scale and Volume remove both limits and use contract-set pricing.

The plans

Plan Base Standard rates Coverage Spend cap
Starter $49/month, fully credited to usage SMS $0.0089/segment · email $0.001 US (NANP) $2,500 / month
Scale $1,000/mo minimum, annual — monthly usage invoiced in arrears after a 30-day trial with $10 usage credit SMS from $0.0045 · email $0.0002 · verify $0.035 flat Worldwide None
Volume Custom Negotiated on your traffic Worldwide None

Scale requires a saved card and includes a 30-day trial with $10 in free usage. Usage above $10 is invoiced at trial end; unused trial credit expires. After the trial, each 30-day invoice is the greater of actual usage or the $1,000 monthly minimum (or a negotiated minimum). Scale does not charge an upfront deposit, refill a prepaid wallet, or credit invoice payments to the wallet. Its usage and service fees are recorded for monthly invoices. Failed invoice payments pause sending until resolved.

Volume rates are negotiated per account and applied as per-account price overrides at contract sign.

Accounts that subscribed before 2026-08 are on the retired Pay as you go / Enterprise plans and keep the terms they signed up under — 3,000 included emails per month, the rates they signed up at, and every capability that was ungated at the time (see the matrix note below).

Capability matrix

Capability Starter Scale Volume Enforced at
sms — SMS sending, brands, campaigns, phone numbers, messaging profiles, compliance ✓ ✓ ✓ route middleware
mms — MMS (media) sending ✓ ✓ POST /messages with type: "MMS"
telegram — Telegram bots and verification delivery ✓ ✓ Telegram bot setup/sending and POST /twofa/verifications with channel: "TELEGRAM"
rcs — RCS messaging ✓ ✓ reserved — no send path yet
twofa — 2FA verifications & templates ✓ ✓ ✓ route middleware
marketing_email — marketing email & campaigns ✓ ✓ ✓ route middleware
multiple_email_domains — more than one verified sending domain ✓ ✓ ✓ second POST /email/identities
multiple_api_keys — more than one API key ✓ ✓ ✓ second API key creation
toll_free — ordering toll-free numbers ✓ ✓ POST /phone-orders
short_code — short codes ✓ ✓ reserved — no ordering path yet
restricted_verticals — SHAFT / age-gated & other restricted campaigns ✓ ✓ POST /campaigns (also edit-retry and resubmit)
dedicated_email_ip — dedicated IP for email ✓ ✓ provisioning (manual)

Tenants calling a gated endpoint they lack the capability for receive 402 CAPABILITY_REQUIRED. A campaign counts as a restricted vertical when ageGated or directLending is set, or the use case is SWEEPSTAKE, POLITICAL, or PUBLIC_SAFETY_RESTRICTED. Starter and legacy Pay-as-you-go accounts attempting a non-US destination receive 403 non_us_destination; accounts past the spend cap receive 402 monthly_cap_reached.

The two capabilities marked reserved have no product surface yet — they carry plan intent so the gate exists the day the feature ships. Nothing is currently blocked by them for anyone.

Accounts on the retired plans keep every capability that was ungated before these checks existed (MMS, Telegram, toll-free ordering, restricted verticals, multiple API keys), so nothing they could do yesterday stops working.

Per-tenant overrides

Admins can grant or revoke individual capabilities on a single subscription without changing the plan. Effective value = subscription override (if set) → plan default → false. Use this for pilots, trials, or revoking a feature for a specific account.

Quotas vs. balance overage

Subscription.includedQuotas is the monthly allowance per metric. Send-time consumption decrements the remaining counter; once it hits zero, further usage on that metric is charged from the tenant's balance. Counters reset every calendar month.

The current plans include no metered allowances — SMS, MMS, email, 2FA, Telegram, number rentals, and mailbox rentals are all billed per use from the balance at the standard PriceItem rate. (The retired Pay as you go plan's 3,000 monthly emails still apply to accounts on it.)

Subscription standing

New accounts must add a credit card before using the dashboard or APIs beyond account setup and billing. The 14-day trial runs from account creation; accounts that never add a card are deleted after that deadline. Existing accounts are grandfathered and do not start a new trial.

Adding a card grants $25 in welcome credit once. Trial accounts have full access to their selected plan: customer messaging, number purchases, 10DLC brand/campaign registration, and all other included features. Trials have no additional recipient restrictions, message prefixes, or daily segment caps. Normal plan capabilities, verification, consent, rate limits, and billing checks still apply.

Usage and registration fees draw from the available balance. Manual top-ups are available in Billing during the trial and charge the saved card on confirmation. Prepaid sends stop when funds cannot cover them and resume after successful funding.

Starter subscription billing and automatic recharge begin when the trial ends. Starter costs $49/month, with each successful $49 payment credited toward usage. Cancel the trial in Billing to stop automatic conversion and recharge; the account becomes read-only. Reminder emails are sent on days 10 and 13. Scale has a separate 30-day minimum waiver with its agreed usage billing terms.

A subscription with status PAST_DUE, INCOMPLETE, or CANCELED retains its plan capabilities in the data model, but send-path checks block new sends until payment and subscription standing are restored.

SMS/MMS sends can include an optional contact profile with names, email, tags, attributes, and tenant-provided consent evidence. This requires contacts.write. The recipient phone number identifies the contact within your account. Existing profiles change only when contact.updateExisting is true; contact writes and Messaging service carrier/delivery updates are processed asynchronously by a separate queue.

Use the main API's /contacts endpoints for individual profile changes, phone lookup, consent history, message history and manual suppression. Profile/consent writes support Idempotency-Key; PATCH/DELETE require expectedVersion. Tenant opt-out evidence blocks sending immediately; tenant opt-in evidence does not clear a recipient's STOP restriction. Consent evidence is stored as supplied.

Enriched contacts stored at billing-cycle end are charged once at the configured CONTACT_STORAGE rate (default $0.001 each). Number-only contacts created from message activity are free. No contact fee is charged per message or per update.

No authentication selected
Client Libraries

Contacts

​

Search contacts

​
Query Parameters
  • search
    Type: string
    max length:  
    200
  • tag
    Type: string
    max length:  
    100
  • consentStatus
    Type: stringenum
    values
    • OPTED_IN
    • OPTED_OUT
    • NEEDS_CONSENT
  • lineType
    Type: string
    max length:  
    100
  • cursor
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Integer numbers.

Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for get/contacts
curl '/contacts?search=&tag=&consentStatus=OPTED_IN&lineType=&cursor=&limit=50' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
{
  "contacts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "tenantId": -9007199254740991,
      "phone": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "tags": [
        "string"
      ],
      "attributes": {},
      "version": -9007199254740991,
      "profileUpdatedAt": "string",
      "carrier": "string",
      "lineType": "string",
      "carrierObservedAt": "string",
      "lastMessageAt": "string",
      "lastChannel": "string",
      "lastStatus": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "deletedAt": "string",
      "billable": true,
      "consents": [
        {
          "channel": "SMS",
          "status": "OPTED_IN",
          "sender": "string",
          "method": "string",
          "capturedAt": "2026-11-21T12:21:17.085Z",
          "disclosureText": "string",
          "sourceUrl": "string",
          "evidence": {},
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "tenantId": -9007199254740991,
          "contactId": "123e4567-e89b-12d3-a456-426614174000",
          "receivedAt": "string",
          "source": "string"
        }
      ],
      "deliveries": [
        {
          "channel": "string",
          "status": "string",
          "_count": 1
        }
      ]
    }
  ],
  "total": 1,
  "nextCursor": "string"
}

Create a contact; existing profiles change only with updateExisting

​
Body
required
application/json
  • phone
    Type: string
    max length:  
    40
    required
  • attributes
    Type: object
  • consents
    Type: array object[] …20
  • email
    Type: string
    max length:  
    254
    Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$Format: email nullable
  • firstName
    Type: string
    min length:  
    1
    max length:  
    100
    nullable
  • lastName
    Type: string
    min length:  
    1
    max length:  
    100
    nullable
  • tags
    Type: array string[] …50
  • updateExisting
    Type: boolean
Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for post/contacts
curl /contacts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN' \
  --data '{
  "firstName": "",
  "lastName": "",
  "email": "",
  "tags": [
    ""
  ],
  "attributes": {
    "additionalProperty": ""
  },
  "updateExisting": false,
  "consents": [
    {
      "channel": "SMS",
      "status": "OPTED_IN",
      "sender": "",
      "method": "",
      "capturedAt": "",
      "disclosureText": "",
      "sourceUrl": "",
      "evidence": {}
    }
  ],
  "phone": ""
}'
{
  "contact": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "tenantId": -9007199254740991,
    "phone": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "tags": [
      "string"
    ],
    "attributes": {},
    "version": -9007199254740991,
    "profileUpdatedAt": "string",
    "carrier": "string",
    "lineType": "string",
    "carrierObservedAt": "string",
    "lastMessageAt": "string",
    "lastChannel": "string",
    "lastStatus": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "deletedAt": "string"
  },
  "skipped": true
}

Read contact and delivery totals

​
Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for get/contacts/summary
curl /contacts/summary \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
{
  "total": 1,
  "optedIn": 1,
  "optedOut": 1,
  "needsConsent": 1,
  "landline": 1,
  "addedThisWeek": 1,
  "delivered": 1,
  "sent": 1
}

Find a contact by phone

​
Query Parameters
  • phone
    Type: string
    max length:  
    40
    required
Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for get/contacts/lookup
curl '/contacts/lookup?phone=' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tenantId": -9007199254740991,
  "phone": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "tags": [
    "string"
  ],
  "attributes": {},
  "version": -9007199254740991,
  "profileUpdatedAt": "string",
  "carrier": "string",
  "lineType": "string",
  "carrierObservedAt": "string",
  "lastMessageAt": "string",
  "lastChannel": "string",
  "lastStatus": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "deletedAt": "string"
}

Read the tenant-provided and provider-observed consent log

​
Query Parameters
  • contactId
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
  • search
    Type: string
    max length:  
    200
  • source
    Type: stringenum
    values
    • TENANT
    • TELNYX
  • since
    Type: string Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$Format: date-time

    the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z

  • status
    Type: stringenum
    values
    • OPTED_IN
    • OPTED_OUT
    • PENDING
    • UNKNOWN
  • cursor
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Integer numbers.

Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for get/contacts/consents
curl '/contacts/consents?contactId=&search=&source=TENANT&since=&status=OPTED_IN&cursor=&limit=50' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
{
  "consents": [
    {
      "channel": "SMS",
      "status": "OPTED_IN",
      "sender": "string",
      "method": "string",
      "capturedAt": "2026-11-21T12:21:17.085Z",
      "disclosureText": "string",
      "sourceUrl": "string",
      "evidence": {},
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "tenantId": -9007199254740991,
      "contactId": "123e4567-e89b-12d3-a456-426614174000",
      "receivedAt": "string",
      "source": "string"
    }
  ],
  "nextCursor": "string"
}

Read contact storage pricing and closed-cycle charges

​
Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for get/contacts/billing
curl /contacts/billing \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
{
  "unitMicros": "string",
  "quantity": 1,
  "estimatedMicros": "string",
  "cycles": [
    {
      "id": "string",
      "cycleStart": "string",
      "cycleEnd": "string",
      "unitMicros": "string",
      "postpaid": true,
      "quantity": 1,
      "amountMicros": "string",
      "chargedAt": "string",
      "snapshottedAt": "string",
      "balanceActionId": 1
    }
  ]
}

Read a contact and its delivery summary

​
Path Parameters
  • id
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
    required
Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for get/contacts/{id}
curl /contacts/123e4567-e89b-12d3-a456-426614174000 \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tenantId": -9007199254740991,
  "phone": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "tags": [
    "string"
  ],
  "attributes": {},
  "version": -9007199254740991,
  "profileUpdatedAt": "string",
  "carrier": "string",
  "lineType": "string",
  "carrierObservedAt": "string",
  "lastMessageAt": "string",
  "lastChannel": "string",
  "lastStatus": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "deletedAt": "string",
  "billable": true,
  "consents": [
    {
      "channel": "SMS",
      "status": "OPTED_IN",
      "sender": "string",
      "method": "string",
      "capturedAt": "2026-11-21T12:21:17.085Z",
      "disclosureText": "string",
      "sourceUrl": "string",
      "evidence": {},
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "tenantId": -9007199254740991,
      "contactId": "123e4567-e89b-12d3-a456-426614174000",
      "receivedAt": "string",
      "source": "string"
    }
  ],
  "deliveries": [
    {
      "channel": "string",
      "status": "string",
      "_count": 1
    }
  ]
}

Update supplied profile fields

​
Path Parameters
  • id
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
    required
Body
required
application/json
  • expectedVersion
    Type: integer
    greater than:  
    0
    max:  
    9007199254740991
    required

    Integer numbers.

  • attributes
    Type: object
  • email
    Type: string
    max length:  
    254
    Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$Format: email nullable
  • firstName
    Type: string
    min length:  
    1
    max length:  
    100
    nullable
  • lastName
    Type: string
    min length:  
    1
    max length:  
    100
    nullable
  • tags
    Type: array string[] …50
Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for patch/contacts/{id}
curl /contacts/123e4567-e89b-12d3-a456-426614174000 \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN' \
  --data '{
  "firstName": "",
  "lastName": "",
  "email": "",
  "tags": [
    ""
  ],
  "attributes": {
    "additionalProperty": ""
  },
  "expectedVersion": 1
}'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tenantId": -9007199254740991,
  "phone": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "tags": [
    "string"
  ],
  "attributes": {},
  "version": -9007199254740991,
  "profileUpdatedAt": "string",
  "carrier": "string",
  "lineType": "string",
  "carrierObservedAt": "string",
  "lastMessageAt": "string",
  "lastChannel": "string",
  "lastStatus": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "deletedAt": "string"
}

Remove contact from active storage; suppressions remain

​
Path Parameters
  • id
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
    required
Query Parameters
  • expectedVersion
    Type: integer
    greater than:  
    0
    max:  
    9007199254740991
    required

    Integer numbers.

Responses
  • 204

    Success

  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for delete/contacts/{id}
curl '/contacts/123e4567-e89b-12d3-a456-426614174000?expectedVersion=1' \
  --request DELETE \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
No Body

Read append-only consent evidence

​
Path Parameters
  • id
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
    required
Query Parameters
  • contactId
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
  • search
    Type: string
    max length:  
    200
  • source
    Type: stringenum
    values
    • TENANT
    • TELNYX
  • since
    Type: string Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$Format: date-time

    the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z

  • status
    Type: stringenum
    values
    • OPTED_IN
    • OPTED_OUT
    • PENDING
    • UNKNOWN
  • cursor
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Integer numbers.

Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for get/contacts/{id}/consents
curl '/contacts/123e4567-e89b-12d3-a456-426614174000/consents?contactId=&search=&source=TENANT&since=&status=OPTED_IN&cursor=&limit=50' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
{
  "consents": [
    {
      "channel": "SMS",
      "status": "OPTED_IN",
      "sender": "string",
      "method": "string",
      "capturedAt": "2026-11-21T12:21:17.085Z",
      "disclosureText": "string",
      "sourceUrl": "string",
      "evidence": {},
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "tenantId": -9007199254740991,
      "contactId": "123e4567-e89b-12d3-a456-426614174000",
      "receivedAt": "string",
      "source": "string"
    }
  ],
  "nextCursor": "string"
}

Append tenant-supplied consent evidence

​
Path Parameters
  • id
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
    required
Body
required
application/json
  • capturedAt
    Type: string Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Format: date-time
    required

    the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z

  • channel
    Type: stringenum
    required
    values
    • SMS
    • MMS
    • RCS
    • EMAIL
    • TELEGRAM
  • method
    Type: string
    min length:  
    1
    max length:  
    100
    required
  • status
    Type: stringenum
    required
    values
    • OPTED_IN
    • OPTED_OUT
    • PENDING
    • UNKNOWN
  • disclosureText
    Type: string
    max length:  
    16000
  • evidence
    Type: object
  • sender
    Type: string
    max length:  
    255
  • sourceUrl
    Type: string
    max length:  
    2048
    Format: uri
Responses
  • application/json
  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for post/contacts/{id}/consents
curl /contacts/123e4567-e89b-12d3-a456-426614174000/consents \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN' \
  --data '{
  "channel": "SMS",
  "status": "OPTED_IN",
  "sender": "",
  "method": "",
  "capturedAt": "",
  "disclosureText": "",
  "sourceUrl": "",
  "evidence": {}
}'
{
  "recorded": true
}

Read contact message history

​
Path Parameters
  • id
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
    required
Query Parameters
  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Integer numbers.

  • cursor
    Type: string
    max length:  
    2000
  • direction
    Type: stringenum
    values
    • OUTBOUND
    • INBOUND
Responses
  • 200

    Success

  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for get/contacts/{id}/messages
curl '/contacts/123e4567-e89b-12d3-a456-426614174000/messages?limit=50&cursor=&direction=OUTBOUND' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
No Body

Read suppression for a sending number

​
Path Parameters
  • id
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
    required
Query Parameters
  • from
    Type: string
    max length:  
    40
    required
Responses
  • 200

    Success

  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for get/contacts/{id}/suppressions
curl '/contacts/123e4567-e89b-12d3-a456-426614174000/suppressions?from=' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN'
No Body

Add an immediate manual block

​
Path Parameters
  • id
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
    required
Body
required
application/json
  • expectedVersion
    Type: integer
    min:  
    0
    max:  
    9007199254740991
    required

    Integer numbers.

  • from
    Type: string
    max length:  
    40
    required
  • note
    Type: string
    min length:  
    1
    max length:  
    1000
    required
Responses
  • 200

    Success

  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for post/contacts/{id}/suppressions
curl /contacts/123e4567-e89b-12d3-a456-426614174000/suppressions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN' \
  --data '{
  "from": "",
  "note": "",
  "expectedVersion": 0
}'
No Body

Remove only a manual block; STOP and non-textable blocks remain

​
Path Parameters
  • id
    Type: string Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Format: uuid
    required
  • suppressionId
    Type: string
    max length:  
    40
    required
Body
required
application/json
  • expectedVersion
    Type: integer
    min:  
    0
    max:  
    9007199254740991
    required

    Integer numbers.

  • note
    Type: string
    min length:  
    1
    max length:  
    1000
    required
Responses
  • 200

    Success

  • 400

    Invalid request

  • 403

    Permission denied

  • 409

    Version or idempotency conflict

Request Example for delete/contacts/{id}/suppressions/{suppressionId}
curl '/contacts/123e4567-e89b-12d3-a456-426614174000/suppressions/{suppressionId}' \
  --request DELETE \
  --header 'Content-Type: application/json' \
  --header 'x-access-key-id: YOUR_SECRET_TOKEN' \
  --header 'x-secret-access-key: YOUR_SECRET_TOKEN' \
  --data '{
  "note": "",
  "expectedVersion": 0
}'
No Body

Brands (Collapsed)

​

10DLC brand registration

Compliance (Collapsed)

​

Compliance events and carrier feedback

Balance (Collapsed)

​

Account balance and usage

Messaging (Collapsed)

​

2FA Verifications (Collapsed)

​

Verification code send and check

2FA Templates (Collapsed)

​

Quotas (Collapsed)

​

Calls (Collapsed)

​

Programmable calling and call history

Phone Orders (Collapsed)

​

Phone number provisioning orders

Webhooks (Collapsed)

​

Outbound event delivery configuration

API Logs (Collapsed)

​

Request log for API traffic

Reports (Collapsed)

​

Models