Version 1
Zexpt REST API
Send transactional email and publish to your WhatsApp Channels from your own code. Everything you do through the API shows up in the dashboard, with the same limits, logs and permissions.
Base URL
https://zexpt.com/api/v1Format
Authentication
api-key headerA first request, to check that your key works:
curl https://zexpt.com/api/v1/account \
-H "api-key: $ZEXPT_API_KEY"Authentication
Create a key in the dashboard under Developers → API keys. Keys start with zx_ and are shown once. Send the key in the api-key header; Authorization: Bearer zx_… works too.
Each key has permissions (scopes). Give a key only what the application needs:
| Scope | Allows |
|---|---|
email | Send email, read email results and your sending domains. |
whatsapp | List your linked numbers and channels; create, read and cancel WhatsApp Channel posts. Only an owner or admin of the organization can create such a key. |
GET /account answers with any valid key. A request with a key that lacks the scope gets 403 missing_scope.
Errors
Errors use the HTTP status and a JSON body with a stable code you can check in your code, and a message you can show or log. Validation errors also list each field in errors.
{
"statusCode": 400,
"message": "Validation failed",
"errors": [
{
"path": "channelId",
"message": "Invalid uuid"
}
]
}| Status | code | Meaning |
|---|---|---|
| 400 | (none), invalid_schedule, invalid_idempotency_key | The body or query is invalid; see errors. |
| 401 | missing_api_key, invalid_api_key | No key, a malformed key, or a revoked key. |
| 403 | missing_scope, organization_suspended | The key lacks the permission, or the organization is suspended. |
| 404 | not_found | The id does not exist, or belongs to another organization. |
| 409 | already_published, publishing, idempotency_in_progress | The request conflicts with the current state. |
| 413 | attachments_too_large | Email attachments over 10 MB in total. |
| 422 | rejected, invalid_post, cannot_post, number_not_linked | Understood, but refused: see the message. |
| 429 | limit_reached (or none) | A sending limit, or too many requests. Retry later. |
| 503 | try_again | Temporary. Retry in a few minutes. |
Rate limits
| What | Limit |
|---|---|
| Requests in general | 300 per minute per IP address |
POST /emails | 600 per minute, plus the hourly, daily and monthly email limits of your plan |
POST /whatsapp/posts | 120 per minute |
| WhatsApp publishing | Each linked number publishes at most one post every 20 seconds. Posts beyond that wait in line and go out in order. |
Over a limit you get 429. Wait and retry; for email, GET /account shows your usage against the limits.
Idempotency
Networks fail. To retry POST /whatsapp/posts safely, send an Idempotency-Key header with a value unique to that post (an order number, a UUID). For 24 hours, a request with the same key and API key does not create a second post: it answers 200 with the first post and the header Idempotent-Replayed: true.
A refused request (4xx) does not use up the key: fix it and send again with the same key.
Send an email
POST/api/v1/emails
Scope email. Sends one message through the same pipeline as SMTP: sender-domain check, limits, DKIM signature with your domain, and an entry in the sending log. 201 with status: "accepted" means the mail server queued it; the delivery result follows within seconds in Get an email.
fromstring | { email, name }
tocontact | contact[]
cc, bcccontact | contact[]
replyTocontact
subjectstring
html, textstring
headersobject
X-… headers only.attachments{ filename, content, contentType }[]
curl -X POST https://zexpt.com/api/v1/emails \
-H "api-key: $ZEXPT_API_KEY" \
-H "content-type: application/json" \
-d '{
"from": {
"email": "orders@yourcompany.com",
"name": "Your Company"
},
"to": [
{
"email": "customer@example.com",
"name": "Customer"
}
],
"subject": "Your order #1001 is confirmed",
"html": "<p>Thanks for your order!</p>",
"text": "Thanks for your order!"
}'{
"id": "77bcf387-0d1e-4c5b-9a8f-2e3d4c5b6a79",
"status": "accepted",
"message": "Accepted and queued by the Zexpt mail server",
"dkimSigned": true
}Get an email
GET/api/v1/emails/{id}
Scope email. The message and one delivery result per recipient:
| Recipient status | Meaning |
|---|---|
queued | Waiting to be sent. |
delivered | The recipient’s mail server accepted it. |
deferred | A temporary problem; retried automatically for up to 2 days. |
bounced | A permanent failure, or not sent because the address is on your suppression list. |
deliveryStatus is partial when some recipients were delivered and others bounced.
curl https://zexpt.com/api/v1/emails/77bcf387-0d1e-4c5b-9a8f-2e3d4c5b6a79 \
-H "api-key: $ZEXPT_API_KEY"{
"id": "77bcf387-0d1e-4c5b-9a8f-2e3d4c5b6a79",
"status": "accepted",
"subject": "Your order #1001 is confirmed",
"deliveryStatus": "delivered",
"deliveries": [
{
"recipient": "customer@example.com",
"status": "delivered",
"attempts": 1,
"dsn": "2.0.0",
"response": "250 2.0.0 OK",
"deliveredAt": "2026-11-22T10:02:11Z"
}
]
}Account
GET/api/v1/account
Any scope. The organization of the key, the key’s name and scopes, and your email limits (0 = no limit beyond your plan) and usage. Handy to test a key.
curl https://zexpt.com/api/v1/account \
-H "api-key: $ZEXPT_API_KEY"{
"organization": {
"id": "b1c2d3e4-…",
"name": "Your Company"
},
"apiKey": {
"name": "Production website",
"prefix": "zx_AbCdEfGh",
"scopes": [
"email",
"whatsapp"
]
},
"mode": "live",
"limits": {
"hourly": 0,
"daily": 0,
"monthly": 0
},
"usage": {
"lastHour": 12,
"today": 140,
"period": 2310,
"periodStart": "2026-11-01T00:00:00.000Z",
"periodEnd": "2026-12-01T00:00:00.000Z"
}
}Domains
GET/api/v1/domains
Scope email. Your sending domains and their verification status.
curl https://zexpt.com/api/v1/domains \
-H "api-key: $ZEXPT_API_KEY"[
{
"name": "yourcompany.com",
"status": "verified",
"verifiedAt": "2026-11-01T09:00:00.000Z",
"lastCheckedAt": "2026-11-22T08:00:00.000Z"
}
]WhatsApp Channels
Publish text, photo and link posts to the WhatsApp Channels of your organization, now or at a set time.
- In the dashboard, link a phone under WhatsApp Channels → Numbers by scanning the QR code with WhatsApp (Settings → Linked devices). The channels that number owns or administers are added by themselves.
- Create an API key with the
whatsappscope under Developers → API keys. - List your channels to get their ids, then create posts.
failed.List numbers
GET/api/v1/whatsapp/numbers
Scope whatsapp. The phone numbers linked to your organization. status is linked, pending (QR code not scanned yet) or disconnected (logged out from the phone: link it again in the dashboard).
curl https://zexpt.com/api/v1/whatsapp/numbers \
-H "api-key: $ZEXPT_API_KEY"[
{
"id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
"label": "Shop phone",
"phone": "+391234567890",
"status": "linked",
"linkedAt": "2026-11-20T15:31:08.000Z",
"createdAt": "2026-11-20T15:30:12.000Z"
}
]List channels
GET/api/v1/whatsapp/channels
Scope whatsapp. Your channels, sorted by name, each with the number that posts there.
iduuid
channelId when you create a post.jidstring
inviteLinkstring | null
followersnumber | null
roleowner | admin | subscriber
canPostboolean
numberobject
curl https://zexpt.com/api/v1/whatsapp/channels \
-H "api-key: $ZEXPT_API_KEY"[
{
"id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Shop news",
"description": "Offers and new arrivals",
"jid": "120363000000000001@newsletter",
"inviteLink": "https://whatsapp.com/channel/0029VaAbCdEf123456",
"followers": 1200,
"role": "owner",
"canPost": true,
"number": {
"id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
"label": "Shop phone",
"phone": "+391234567890",
"status": "linked"
}
}
]Get a channel
GET/api/v1/whatsapp/channels/{id}
Scope whatsapp. One channel, same fields as in the list.
curl https://zexpt.com/api/v1/whatsapp/channels/9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d \
-H "api-key: $ZEXPT_API_KEY"{
"id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Shop news",
"description": "Offers and new arrivals",
"jid": "120363000000000001@newsletter",
"inviteLink": "https://whatsapp.com/channel/0029VaAbCdEf123456",
"followers": 1200,
"role": "owner",
"canPost": true,
"number": {
"id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
"label": "Shop phone",
"phone": "+391234567890",
"status": "linked"
}
}Create a post
POST/api/v1/whatsapp/posts
Scope whatsapp. Creates a post and queues it: published right away, or at scheduledAt. Answers 201 with the post in status scheduled.
channelIduuid
typetext | image | link
image when imageUrl is set, link when linkUrl is set, else text.bodystring
imageUrlhttps URL
linkUrlhttps URL
linkTitle, linkDescriptionstring
scheduledAtISO 8601 date
A photo post, scheduled:
{
"channelId": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"imageUrl": "https://www.example.com/images/sunset.jpg",
"body": "🌅 Sunset in Sicily. Who is coming with us?",
"scheduledAt": "2026-11-23T09:00:00+01:00"
}| Refused with | When |
|---|---|
422 invalid_post | Text missing, photo missing, or caption too long. |
422 cannot_post | The channel’s number is only a follower there. |
422 number_not_linked | The number was logged out: link it again in the dashboard. |
404 not_found | Unknown channel id. |
curl -X POST https://zexpt.com/api/v1/whatsapp/posts \
-H "api-key: $ZEXPT_API_KEY" \
-H "Idempotency-Key: tours-2026-11-22" \
-H "content-type: application/json" \
-d '{
"channelId": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"body": "✨ New tours are online! Places are limited 👇",
"linkUrl": "https://www.example.com/tours",
"linkTitle": "New departures",
"linkDescription": "Small groups, local guides."
}'{
"id": "5f0c6a3e-2b7d-4c1a-9e8f-1a2b3c4d5e6f",
"channel": {
"id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Shop news"
},
"type": "link",
"body": "✨ New tours are online! Places are limited 👇",
"imageUrl": null,
"linkUrl": "https://www.example.com/tours",
"linkTitle": "New departures",
"linkDescription": "Small groups, local guides.",
"status": "scheduled",
"scheduledAt": "2026-11-22T10:00:00.000Z",
"sentAt": null,
"confirmed": null,
"whatsappMessageId": null,
"attempts": 0,
"error": null,
"campaignId": null,
"createdAt": "2026-11-22T10:00:00.000Z"
}Get a post
GET/api/v1/whatsapp/posts/{id}
Scope whatsapp. The post and its outcome. Poll it after creating a post, for example every 10 seconds until status is sent or failed.
statusstring
sentAtdate | null
confirmedboolean | null
whatsappMessageIdstring | null
attemptsnumber
errorstring | null
campaignIduuid | null
curl https://zexpt.com/api/v1/whatsapp/posts/5f0c6a3e-2b7d-4c1a-9e8f-1a2b3c4d5e6f \
-H "api-key: $ZEXPT_API_KEY"{
"id": "5f0c6a3e-2b7d-4c1a-9e8f-1a2b3c4d5e6f",
"channel": {
"id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Shop news"
},
"type": "link",
"body": "✨ New tours are online! Places are limited 👇",
"imageUrl": null,
"linkUrl": "https://www.example.com/tours",
"linkTitle": "New departures",
"linkDescription": "Small groups, local guides.",
"status": "sent",
"scheduledAt": "2026-11-22T10:00:00.000Z",
"sentAt": "2026-11-22T10:00:04.512Z",
"confirmed": true,
"whatsappMessageId": "3EB0A1B2C3D4E5F6",
"attempts": 1,
"error": null,
"campaignId": null,
"createdAt": "2026-11-22T10:00:00.000Z"
}List posts
GET/api/v1/whatsapp/posts
Scope whatsapp. Posts, newest first, including those made in the dashboard.
channelIduuid
statusstring
page, pageSizenumber
curl https://zexpt.com/api/v1/whatsapp/posts?channelId=9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d&status=sent&page=1&pageSize=25 \
-H "api-key: $ZEXPT_API_KEY"{
"total": 42,
"page": 1,
"pageSize": 25,
"items": [
{
"id": "5f0c6a3e-2b7d-4c1a-9e8f-1a2b3c4d5e6f",
"channel": {
"id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Shop news"
},
"type": "link",
"body": "✨ New tours are online! Places are limited 👇",
"imageUrl": null,
"linkUrl": "https://www.example.com/tours",
"linkTitle": "New departures",
"linkDescription": "Small groups, local guides.",
"status": "sent",
"scheduledAt": "2026-11-22T10:00:00.000Z",
"sentAt": "2026-11-22T10:00:04.512Z",
"confirmed": true,
"whatsappMessageId": "3EB0A1B2C3D4E5F6",
"attempts": 1,
"error": null,
"campaignId": null,
"createdAt": "2026-11-22T10:00:00.000Z"
}
]
}Cancel a post
DELETE/api/v1/whatsapp/posts/{id}
Scope whatsapp. Deletes a post that has not gone out: scheduled, draft or failed. A post that is being published or is published answers 409 (publishing or already_published): delete a published post in the WhatsApp app.
curl -X DELETE https://zexpt.com/api/v1/whatsapp/posts/5f0c6a3e-2b7d-4c1a-9e8f-1a2b3c4d5e6f \
-H "api-key: $ZEXPT_API_KEY"{
"id": "5f0c6a3e-2b7d-4c1a-9e8f-1a2b3c4d5e6f",
"deleted": true
}Post statuses
| Status | Meaning |
|---|---|
draft | Saved in the dashboard, not queued. |
scheduled | Queued: goes out at scheduledAt, or as soon as the number’s turn comes. Also while it waits for a retry. |
sending | Being published right now. |
sent | Published on the channel. |
failed | Not published; see error. Create the post again once the cause is fixed. |
Text formatting
WhatsApp formatting works in the body of every post:
| Write | Shows as |
|---|---|
*bold* | bold |
_italic_ | italic |
~strikethrough~ | |
```monospace``` | monospace |
\n | A new line (in JSON). |
Need help? Write to us from the contact page.