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 IDx-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 withGET /telegram/chats?type=channelsand 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 uniqueIdempotency-Keyfor each intentional send and reuse that key and body on retries. - HTTP
201/sentmeans Telegram accepted the message, not that anyone read it. It is charged once at the account's Telegram outbound message rate. HTTP422/failedmeans rejected and is not charged. HTTP202/unknownis 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/messagesand an individual outcome withGET /telegram/messages/:id. FollownextCursorusingbeforefor additional pages. - Subscribe to
telegram.sent,telegram.received,telegram.failed, andtelegram.unknownthrough the standard customer webhooks. Deduplicate retries using the stable event ID. PATCH /telegram/chats/:idwith{ "enabled": false }disconnects a chat. Re-enable after restoring Telegram permissions.DELETE /telegram/botdisconnects your bot;DELETE /telegram/linkremoves 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.
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 astype: "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: trueand the sameX-Message-Id. Each HTTP attempt has its ownX-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 vianextToken.
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. Thebodymust start with[Otter]. Otherwise the request returns400withcode: "test_prefix_required".- Heavy rate limit. Default caps are 5/min, 30/hour, 100/day per account. Exceeding any window returns
429withcode: "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.receivedis 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 —
fromIdentityIdselects a verifiedEmailIdentity. Omit it to send from the system default sender. - SMS —
fromPhoneNumberIdselects a tenant phone number that isASSIGNED/ACTIVEand 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 —
templateIdand 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>wherev1isHMAC-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
dnsRecordsarray 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.receivedis 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/contentTypeare optional. When omitted, Blocx uses the responseContent-DispositionandContent-Type, falling back to the URL basename andapplication/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:
400withcodeattachment_blockedorattachment_fetch_failed, or413withattachment_too_largewhen 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:
- Capabilities — boolean feature flags that decide which endpoints the tenant can call.
- Included quotas — a monthly allowance of metered usage per metric. Once exhausted, additional usage is charged from the account balance at the standard
PriceItemrate. - 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.
Contact profiles and consent evidence
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.