Puxh
Sender API

Send expected messages with a clear contract.

JSON HTTP API: each sender authenticates with a key, unknown fields are refused and error codes are stable.

Nothing is sent from this page: copy the request and run it from your server, with your key in the PUXH_API_KEY variable.

Authentication

Create a key in the sender space and send it as a Bearer token. A key belongs to one sender and can be restricted to IP addresses.

The key is shown only once: keep it server-side and revoke it if it leaks.

Base URL supplied by Puxh
https://<your-puxh-api-url>
Header on every request
Authorization: Bearer pxh_••••••••

POST/v1/messages

Send a message

The recipient is named by their Puxh ID, the template must be approved and the variables fill it. An idempotency key protects retries for 24 hours.

Public text is not confidential

The publicText field may show in a notification read by Google or Apple. It may cite the variables of the template text: their values then appear in clear, so never put a code or personal data in it. The rest of the message is encrypted.

ParameterTypeDescription
torequiredstringRecipient’s Puxh ID.
templaterequiredstringApproved template for this sender: a version (order_shipped.v2) or the name alone (order_shipped) for the latest approved version.
variablesoptionalobjectValues of the variables the template declares, one entry per variable.
variables.<name>optionalstringValue of one variable, as text, 200 characters at most.
expiresInoptionalintegerFor an otp template only: code validity in seconds, from 30 to 3600 (300 by default).
lockedoptionalbooleanProtected message: the recipient shows it with Face ID, fingerprint, the phone passcode or a Puxh PIN, and it hides again when closed. Notification “Vous avez reçu un message protégé”, without content. Blue or green badge; refused for an otp template.
oneViewoptionalbooleanView once: like locked, but the message is deleted after its first reading. Blue or green badge; refused for an otp template.
Idempotency-Keyoptional · headerstring1 to 255 characters; the same key returns the first response for 24 h.

POST/v1/messages/free-form

Send a free-form message

After a recipient replies with a reply button, you may send them a single free-form message within 24 hours, without a template: a text and up to three buttons. With the green badge, you may send them to any recipient who has accepted you.

ParameterTypeDescription
torequiredstringPuxh ID of the recipient who just replied to you, or of any recipient who has accepted you with the green badge.
textrequiredstringMessage text, 1 to 1000 characters.
buttonsoptionalarrayOptional: 1 to 3 url, code or reply buttons, with a single reply.
buttons[].idrequiredstringButton ID, sent back to your webhook with each reply.
buttons[].typerequiredstringurl opens a link, code copies a code, reply opens an answer sent to your webhook.
buttons[].labelrequiredstringButton label, 24 characters at most, distinct from the other buttons.
buttons[].urloptionalstringFor a url button: https:// link, 2048 characters at most.
buttons[].codeoptionalstringFor a code button: copied text, 1 to 100 characters.
Idempotency-Keyoptional · headerstring1 to 255 characters; the same key returns the first response for 24 h.

GET/v1/messages/{messageId}

Track a message

Returns the status of a send, without its content.

ParameterTypeDescription
messageIdrequired · pathstringIdentifier returned by the send.

POST/v1/approval-requests

Request permission without a message

Creates an authorization request with a short code, without free text.

ParameterTypeDescription
torequiredstringPuxh ID of the person to ask for permission.

POST/v1/templates

Submit a template

The template goes through review and can be sent only once approved (reference order_shipped.v1). The decision arrives with template.reviewed.

ParameterTypeDescription
namerequiredstringTemplate name: lowercase letters, digits and _, 2 to 48 characters.
definitionrequiredobjectTemplate content submitted for review.
definition.typerequiredstringotp, utility or info. An otp template only has type and language: Puxh sets its text.
definition.languageoptionalstringTemplate language: fr, en, es, pt, de, it, nl, ar, zh, ja, ko, hi, ru, tr, sw, pl; fr by default.
definition.textoptionalstringMessage text, except for an otp template. A variable is written {orderId} and must be declared.
definition.variablesoptionalobjectVariables used in the text or the buttons, one entry per name.
definition.variables.<name>.typerequiredstringtext or number.
definition.variables.<name>.maxLengthrequiredintegerMaximum length of the value, from 1 to 200 characters.
definition.notificationModerequiredstringsecure, plain or encrypted. An otp template is always secure.
definition.publicTextoptionalstringNotification text, required in plain mode, without personal data. It only cites declared template variables, filled at send time.
definition.buttonsoptionalarray1 to 3 buttons, for a utility or info template. An otp template never has any.
definition.buttons[].idrequiredstringButton ID, sent back to your webhook with each reply.
definition.buttons[].typerequiredstringurl opens a link, code copies a code, reply opens an answer sent to your webhook.
definition.buttons[].labelrequiredstringButton label, 24 characters at most, distinct from the other buttons.
definition.buttons[].urloptionalstringFor a url button: https:// link, 2048 characters at most; the path may use variables.
definition.buttons[].codeoptionalstringFor a code button: copied text, 1 to 100 characters.

GET/v1/templates/{template}

Read a template

Returns a template version with its review state and, for a refusal, the reason.

ParameterTypeDescription
templaterequired · pathstringVersion reference, as used when sending: the name, then .v and the number (order_shipped.v1).

GET/v1/balance

Read the balance

Returns the account balance: credits, debt and frozen. Top-ups happen in the sender space.

No parameter: the API key is enough.

Account API

With an account key (pxa_…), create your clients’ senders, get them verified and create their sending keys. An account key sends no message.

  • POST /v1/senders — creates a sender with the alert badge and an optional website
  • GET /v1/senders — lists the senders of your account
  • GET /v1/senders/{senderId} — reads a sender, its badge and its verification state
  • PUT /v1/senders/{senderId}/website — sets the website, frozen during a review or under a badge
  • POST /v1/senders/{senderId}/verification/email — sends the code to the client’s work address
  • POST /v1/senders/{senderId}/verification/email/confirm — confirms the code and puts the case in review
  • POST /v1/senders/{senderId}/verification/documents — uploads the holder type, its name and the documents (identity or company); the domain TXT is checked
  • POST /v1/senders/{senderId}/api-keys — creates a pxh_ sending key, shown only once
  • DELETE /v1/senders/{senderId}/api-keys/{keyId} — revokes a key of this sender

The blue or green badge requires the sender’s website: a code sent to your client’s work e-mail for blue; for green, an identity or company document and the TXT record “puxh-verification=” followed by the sender id, at the root of the website domain.

The sender space rules apply and your senders share your balance.

Header on every request
Authorization: Bearer pxa_••••••••
Create a sender
{
  "name": "Boutique Awa",
  "website": "https://boutique-awa.ci"
}
Sender
{
  "senderId": "snd_8kq2",
  "pushId": "BOUAWA3F",
  "name": "Boutique Awa",
  "website": "https://boutique-awa.ci",
  "badge": "alert",
  "status": "active",
  "verification": "pro_email",
  "verificationStatus": "in_review",
  "rejectionReason": null
}
Pro email verification
POST /v1/senders/snd_8kq2/verification/email
{ "email": "awa@boutique-awa.ci" }
→ 200 { "challengeId": "…", "expiresAt": …, "retryAt": … }

POST /v1/senders/snd_8kq2/verification/email/confirm
{ "challengeId": "…", "code": "012345" }
→ 200 { "status": "in_review", "domain": "boutique-awa.ci" }

Stable errors

An error carries a code, a message and, for validation, the errors list, each message preceded by its field (template: …). Branch your logic on code.

  • 400 invalid_request — invalid body or parameter
  • 401 unauthorized — missing, unknown or revoked key, or rejected IP
  • 402 insufficient_balance — balance used up: top up from the sender space
  • 403 balance_frozen — balance frozen by a suspension or a refund
  • 403 sender_suspended — the key’s sender is suspended
  • 404 sender_not_found — the key’s sender cannot be found
  • 404 message_not_found — unknown message, or one sent by another sender
  • 404 template_not_found — template version unknown to the key’s sender
  • 409 idempotency_key_reused — the same key was reused for another request
  • 409 template_in_review — a version of this template is already in review
  • 409 template_name_deleted — name of a deleted template: choose another one
  • 400 template_link_not_allowed — link outside the sender’s verified domains
  • 403 free_form_not_allowed — no free-form message possible for this recipient
  • 403 protection_not_allowed — protected message (locked, oneView) reserved to the blue and green badges
  • 422 free_form_refused — message refused by the check: fix it and send it again
  • 503 free_form_review_unavailable — check unavailable: try again
  • 429 quota_exceeded — rate limit or business quota reached
  • 500 / 503 internal — Puxh error or sending briefly paused: try again later
4xx / 5xx
{
  "code": "invalid_request",
  "message": "template is unknown or not approved for this sender",
  "errors": [
    "template: unknown or not approved for this sender"
  ]
}

Verify webhooks

Puxh sends your recipients’ replies, the progress of your sends and review decisions to your HTTPS URL. Check the HMAC-SHA256 signature (timestamp, a dot, then the raw body).

A reply button sends message.reply with messageId, the button ID (button) and the typed text (text).

A reply opens a free-form message for 24 hours (see “Send a free-form message”).

The decision on a template arrives with template.reviewed, with the reason of a refusal.

After queued, you receive message.sent when the message is delivered to the devices, then message.delivered when a first device fetched it, or message.failed with reason (expired, refused or withdrawn).

Events: message.reply, message.sent, message.delivered, message.failed, template.reviewed and puxh.test (“Test” button).

With an ECDH P-256 public key, the body is encrypted (epk, iv, ct): decrypt it on your server after checking the signature.

Answer with a 2xx within 10 seconds, otherwise Puxh retries for up to 6 hours. Deduplicate with X-Puxh-Delivery.

Received headers
X-Puxh-Delivery: whd_01JABCDEF
X-Puxh-Timestamp: 1793117100
X-Puxh-Signature: v1=<hex-hmac-sha256>
Body received: user reply
{
  "event": "message.reply",
  "messageId": "3f6c1d2e-8b4a-4c7e-9d15-6a2b0e4f7c81",
  "button": "question",
  "text": "Puis-je changer l’adresse de livraison ?",
  "at": "2026-10-27T16:05:00.000Z"
}
Body received: review decision
{
  "event": "template.reviewed",
  "template": "order_shipped.v1",
  "status": "rejected",
  "reason": "Le texte contient une promotion.",
  "at": "2026-10-29T09:30:00.000Z"
}
Body received: send progress
{
  "event": "message.failed",
  "messageId": "3f6c1d2e-8b4a-4c7e-9d15-6a2b0e4f7c81",
  "reason": "refused",
  "at": "2026-10-27T16:10:00.000Z"
}
Server-side verification
expected = HMAC_SHA256(secret, timestamp + "." + rawBody)
accept only if signature == "v1=" + hex(expected)
reject if abs(now - timestamp) > 300 seconds
ignore an already processed X-Puxh-Delivery