Phone verification

The verification API sends a 6-digit code on WhatsApp, then tells you whether the code your user typed is the right one. MailPulse generates the code, sends it through your organization's WhatsApp transport, counts attempts and handles expiry: your application never sees the code.

Authentication is the same as POST /api/v1/messages (Authorization: Bearer mp_live_xxx). The organization needs a connected Evolution instance, otherwise the API answers 409. WhatsApp Cloud API is not supported for codes yet (see below).

Send a code

curl -X POST $MAILPULSE_URL/api/v1/verifications \
  -H "Authorization: Bearer $MAILPULSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"whatsapp","to":"+2250700000000","locale":"en","reference":"signup_42"}'

to must be international (+… or 00…). locale is fr (default) or en; any other value is rejected. reference is optional and echoed back. sender_id, optional, names one of the key's application numbers (GET /api/v1/whatsapp/numbers); without it, the default number sends, or another WhatsApp Web number of the application when the default is on Meta. Response 201:

{
  "id": "cmf8x2k0p0000abcd1234efgh",
  "status": "pending",
  "channel": "whatsapp",
  "to_masked": "+225 07 ** ** ** 00",
  "reference": "signup_42",
  "expires_at": "2026-09-23T10:10:00.000Z",
  "created_at": "2026-09-23T10:00:00.000Z",
  "approved_at": null
}

If the provider does not confirm the send (timeout, transport error), the answer is still 201 and the verification stays pending: the message may have gone out, and a code that arrives late works.

Check the code

curl -X POST $MAILPULSE_URL/api/v1/verifications/cmf8x2k0p0000abcd1234efgh/check \
  -H "Authorization: Bearer $MAILPULSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

Right code: 200 {"id":"…","status":"approved"}. Otherwise 422 with status and error: pending + code_invalide (wrong code, retry), max_attempts + trop_de_tentatives (5 wrong codes), expired, canceled (a newer code was sent), approved (already used) or failed (never sent), all with expire.

Read a verification

curl $MAILPULSE_URL/api/v1/verifications/cmf8x2k0p0000abcd1234efgh \
  -H "Authorization: Bearer $MAILPULSE_API_KEY"

Returns the current state. Another organization's verification answers 404.

Reverse verification (recommended)

A code sent by MailPulse goes to someone who never wrote to the number, the signal WhatsApp watches most on a WhatsApp Web number. In reverse mode the person sends the code to your application's number from a wa.me link: nothing leaves MailPulse, and the number the message comes from proves it is theirs.

Send "mode": "reverse" with the usual body. The 201 response adds message (the text to send, code included) and wa_link, returned once. Show the link, then poll GET /api/v1/verifications/{id} until approved. MailPulse approves when the message arrives from the right number with the right code, answers the person, and does not forward that message to the application's chatbot. Only the application's own WhatsApp Web number can receive these codes (409 inverse_indisponible otherwise), and check refuses a reverse verification (409 verification_inverse).

Resend and limits

Send again for the same number: the previous pending verification is canceled. Limits per recipient number and organization: 1 per minute, 3 per hour, 5 per day. Per sending number, codes sent by MailPulse only: 1 every 5 s, 6 per minute, 80 per hour, 500 per day; 1 every 10 s, 3 per minute, 30 per hour, 150 per day for a number paired by QR code less than 30 days ago; no code for 30 minutes after WhatsApp throttles the number. Also 20 per hour per API key, 100 per hour per organization, and 30 per minute per organization shared with API WhatsApp messages. Beyond them: 429 with Retry-After.

WhatsApp Cloud API

Outside the 24-hour window opened by the user, Meta accepts a free-form message and never delivers it. A code then needs an approved authentication template, which verifications do not support yet. Until they do, an organization on WhatsApp Cloud API gets 409 whatsapp_indisponible instead of a code that would never arrive.