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/v1

Format

JSON request and response bodies, UTF-8

Authentication

An API key in the api-key header

A 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:

ScopeAllows
emailSend email, read email results and your sending domains.
whatsappList 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.

Keep keys on your server. A key in a website, a mobile app or a public repository can be used by anyone: revoke it at once under Developers → API keys and create a new one.

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.

Example error
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "path": "channelId",
      "message": "Invalid uuid"
    }
  ]
}
StatuscodeMeaning
400(none), invalid_schedule, invalid_idempotency_keyThe body or query is invalid; see errors.
401missing_api_key, invalid_api_keyNo key, a malformed key, or a revoked key.
403missing_scope, organization_suspendedThe key lacks the permission, or the organization is suspended.
404not_foundThe id does not exist, or belongs to another organization.
409already_published, publishing, idempotency_in_progressThe request conflicts with the current state.
413attachments_too_largeEmail attachments over 10 MB in total.
422rejected, invalid_post, cannot_post, number_not_linkedUnderstood, but refused: see the message.
429limit_reached (or none)A sending limit, or too many requests. Retry later.
503try_againTemporary. Retry in a few minutes.

Rate limits

WhatLimit
Requests in general300 per minute per IP address
POST /emails600 per minute, plus the hourly, daily and monthly email limits of your plan
POST /whatsapp/posts120 per minute
WhatsApp publishingEach 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 }

Required. The domain must be one of your verified sending domains.

tocontact | contact[]

Required. A contact is an email string or { email, name }. At most 100 recipients in total with cc and bcc.

cc, bcccontact | contact[]

Optional. BCC addresses are never written into the message.

replyTocontact

Optional.

subjectstring

Required, up to 998 characters.

html, textstring

At least one. Send both for the best deliverability.

headersobject

Optional. Custom X-… headers only.

attachments{ filename, content, contentType }[]

Optional. Up to 10 files, content in base64, 10 MB in total.
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!"
}'
Response
{
  "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 statusMeaning
queuedWaiting to be sent.
deliveredThe recipient’s mail server accepted it.
deferredA temporary problem; retried automatically for up to 2 days.
bouncedA 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"
Response
{
  "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"
Response
{
  "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"
Response
[
  {
    "name": "yourcompany.com",
    "status": "verified",
    "verifiedAt": "2026-11-01T09:00:00.000Z",
    "lastCheckedAt": "2026-11-22T08:00:00.000Z"
  }
]

WhatsApp

WhatsApp Channels

Publish text, photo and link posts to the WhatsApp Channels of your organization, now or at a set time.

  1. 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.
  2. Create an API key with the whatsapp scope under Developers → API keys.
  3. List your channels to get their ids, then create posts.
Posts are queued and published by the linked number in the background, usually within seconds. Read the outcome with Get a post. If the phone is offline, the post waits and is retried every minute for about 30 minutes before it is marked 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"
Response
[
  {
    "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

Use it as channelId when you create a post.

jidstring

The channel’s WhatsApp id.

inviteLinkstring | null

The public link to follow the channel.

followersnumber | null

Followers, as last read from WhatsApp.

roleowner | admin | subscriber

The number’s role in the channel.

canPostboolean

Whether WhatsApp lets the number post here (owner or admin).

numberobject

The linked number: id, label, phone, status.
curl https://zexpt.com/api/v1/whatsapp/channels \
  -H "api-key: $ZEXPT_API_KEY"
Response
[
  {
    "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"
Response
{
  "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

Required. A channel whose canPost is true.

typetext | image | link

Optional. Without it: image when imageUrl is set, link when linkUrl is set, else text.

bodystring

The text, up to 4,096 characters (1,024 as a photo caption). Required for text and link posts. Supports WhatsApp formatting.

imageUrlhttps URL

The photo (JPEG or PNG, up to 16 MB) for photo posts, or a preview image for link cards. Must be publicly reachable.

linkUrlhttps URL

Required for link posts. Links without https:// are completed.

linkTitle, linkDescriptionstring

Optional title (200) and description (400) of the link card.

scheduledAtISO 8601 date

Optional. Publish at this time (up to a year ahead). In the past, or within the next minute, means now.

A photo post, scheduled:

Request body
{
  "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 withWhen
422 invalid_postText missing, photo missing, or caption too long.
422 cannot_postThe channel’s number is only a follower there.
422 number_not_linkedThe number was logged out: link it again in the dashboard.
404 not_foundUnknown 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."
}'
Response
{
  "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

When it was published.

confirmedboolean | null

true: WhatsApp confirmed the post. false: no confirmation within 15 seconds (it is usually published anyway).

whatsappMessageIdstring | null

WhatsApp’s id of the published message.

attemptsnumber

Publishing attempts so far.

errorstring | null

Why it failed, or why it is being retried.

campaignIduuid | null

Set when the post belongs to an email campaign made in the dashboard.
curl https://zexpt.com/api/v1/whatsapp/posts/5f0c6a3e-2b7d-4c1a-9e8f-1a2b3c4d5e6f \
  -H "api-key: $ZEXPT_API_KEY"
Response
{
  "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

Optional. Only this channel.

statusstring

Optional. draft, scheduled, sending, sent or failed.

page, pageSizenumber

Optional. Page from 1; pageSize up to 100 (default 25).
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"
Response
{
  "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"
Response
{
  "id": "5f0c6a3e-2b7d-4c1a-9e8f-1a2b3c4d5e6f",
  "deleted": true
}

Post statuses

StatusMeaning
draftSaved in the dashboard, not queued.
scheduledQueued: goes out at scheduledAt, or as soon as the number’s turn comes. Also while it waits for a retry.
sendingBeing published right now.
sentPublished on the channel.
failedNot published; see error. Create the post again once the cause is fixed.

Text formatting

WhatsApp formatting works in the body of every post:

WriteShows as
*bold*bold
_italic_italic
~strikethrough~strikethrough
```monospace```monospace
\nA new line (in JSON).

Need help? Write to us from the contact page.