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.
https://<your-puxh-api-url>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.
| Parameter | Type | Description |
|---|---|---|
torequired | string | Recipient’s Puxh ID. |
templaterequired | string | Approved template for this sender: a version (order_shipped.v2) or the name alone (order_shipped) for the latest approved version. |
variablesoptional | object | Values of the variables the template declares, one entry per variable. |
variables.<name>optional | string | Value of one variable, as text, 200 characters at most. |
expiresInoptional | integer | For an otp template only: code validity in seconds, from 30 to 3600 (300 by default). |
lockedoptional | boolean | Protected 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. |
oneViewoptional | boolean | View once: like locked, but the message is deleted after its first reading. Blue or green badge; refused for an otp template. |
Idempotency-Keyoptional · header | string | 1 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.
| Parameter | Type | Description |
|---|---|---|
torequired | string | Puxh ID of the recipient who just replied to you, or of any recipient who has accepted you with the green badge. |
textrequired | string | Message text, 1 to 1000 characters. |
buttonsoptional | array | Optional: 1 to 3 url, code or reply buttons, with a single reply. |
buttons[].idrequired | string | Button ID, sent back to your webhook with each reply. |
buttons[].typerequired | string | url opens a link, code copies a code, reply opens an answer sent to your webhook. |
buttons[].labelrequired | string | Button label, 24 characters at most, distinct from the other buttons. |
buttons[].urloptional | string | For a url button: https:// link, 2048 characters at most. |
buttons[].codeoptional | string | For a code button: copied text, 1 to 100 characters. |
Idempotency-Keyoptional · header | string | 1 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.
| Parameter | Type | Description |
|---|---|---|
messageIdrequired · path | string | Identifier returned by the send. |
POST/v1/approval-requests
Request permission without a message
Creates an authorization request with a short code, without free text.
| Parameter | Type | Description |
|---|---|---|
torequired | string | Puxh 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.
| Parameter | Type | Description |
|---|---|---|
namerequired | string | Template name: lowercase letters, digits and _, 2 to 48 characters. |
definitionrequired | object | Template content submitted for review. |
definition.typerequired | string | otp, utility or info. An otp template only has type and language: Puxh sets its text. |
definition.languageoptional | string | Template language: fr, en, es, pt, de, it, nl, ar, zh, ja, ko, hi, ru, tr, sw, pl; fr by default. |
definition.textoptional | string | Message text, except for an otp template. A variable is written {orderId} and must be declared. |
definition.variablesoptional | object | Variables used in the text or the buttons, one entry per name. |
definition.variables.<name>.typerequired | string | text or number. |
definition.variables.<name>.maxLengthrequired | integer | Maximum length of the value, from 1 to 200 characters. |
definition.notificationModerequired | string | secure, plain or encrypted. An otp template is always secure. |
definition.publicTextoptional | string | Notification text, required in plain mode, without personal data. It only cites declared template variables, filled at send time. |
definition.buttonsoptional | array | 1 to 3 buttons, for a utility or info template. An otp template never has any. |
definition.buttons[].idrequired | string | Button ID, sent back to your webhook with each reply. |
definition.buttons[].typerequired | string | url opens a link, code copies a code, reply opens an answer sent to your webhook. |
definition.buttons[].labelrequired | string | Button label, 24 characters at most, distinct from the other buttons. |
definition.buttons[].urloptional | string | For a url button: https:// link, 2048 characters at most; the path may use variables. |
definition.buttons[].codeoptional | string | For 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.
| Parameter | Type | Description |
|---|---|---|
templaterequired · path | string | Version 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 websiteGET /v1/senders— lists the senders of your accountGET /v1/senders/{senderId}— reads a sender, its badge and its verification statePUT /v1/senders/{senderId}/website— sets the website, frozen during a review or under a badgePOST /v1/senders/{senderId}/verification/email— sends the code to the client’s work addressPOST /v1/senders/{senderId}/verification/email/confirm— confirms the code and puts the case in reviewPOST /v1/senders/{senderId}/verification/documents— uploads the holder type, its name and the documents (identity or company); the domain TXT is checkedPOST /v1/senders/{senderId}/api-keys— creates a pxh_ sending key, shown only onceDELETE /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.
Authorization: Bearer pxa_••••••••{
"name": "Boutique Awa",
"website": "https://boutique-awa.ci"
}{
"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
}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 parameter401 unauthorized— missing, unknown or revoked key, or rejected IP402 insufficient_balance— balance used up: top up from the sender space403 balance_frozen— balance frozen by a suspension or a refund403 sender_suspended— the key’s sender is suspended404 sender_not_found— the key’s sender cannot be found404 message_not_found— unknown message, or one sent by another sender404 template_not_found— template version unknown to the key’s sender409 idempotency_key_reused— the same key was reused for another request409 template_in_review— a version of this template is already in review409 template_name_deleted— name of a deleted template: choose another one400 template_link_not_allowed— link outside the sender’s verified domains403 free_form_not_allowed— no free-form message possible for this recipient403 protection_not_allowed— protected message (locked, oneView) reserved to the blue and green badges422 free_form_refused— message refused by the check: fix it and send it again503 free_form_review_unavailable— check unavailable: try again429 quota_exceeded— rate limit or business quota reached500 / 503 internal— Puxh error or sending briefly paused: try again later
{
"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.
X-Puxh-Delivery: whd_01JABCDEF
X-Puxh-Timestamp: 1793117100
X-Puxh-Signature: v1=<hex-hmac-sha256>{
"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"
}{
"event": "template.reviewed",
"template": "order_shipped.v1",
"status": "rejected",
"reason": "Le texte contient une promotion.",
"at": "2026-10-29T09:30:00.000Z"
}{
"event": "message.failed",
"messageId": "3f6c1d2e-8b4a-4c7e-9d15-6a2b0e4f7c81",
"reason": "refused",
"at": "2026-10-27T16:10:00.000Z"
}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
Puxh