Send verification code
Creates a new user_verification attempt, supersedes any previous active code for the same number, and sends a newly generated code. Do not use messages/send when you need the full verify lifecycle.
When to use it. Login, phone confirmation, or any OTP you will verify later via API.
Code example
Correct: Send OTP over international SMS
curl --location 'https://raselsms.com/api/v2/verification/send' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"to":"+963912345678","channel":"int_sms"}'Incorrect: Incorrect: bare channel name
curl --location 'https://raselsms.com/api/v2/verification/send' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"to":"+963912345678","channel":"sms"}'Values such as sms, whatsapp, or auto alone are rejected.
Response example
200 — Send OTP over international SMS
{ "verificationId": "6800abc123def4567890fedc", "status": "sent", "channel": "int_sms", "expiresAt": "2026-09-05T10:10:00.000Z", "resendAvailableAt": "2026-09-05T10:01:00.000Z", "resendCount": 0}400 — Incorrect: bare channel name
{ "success": false, "code": "VALIDATION_ERROR", "error": "Unsupported verification channel"}Values such as sms, whatsapp, or auto alone are rejected.
401 — Missing or invalid API key.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "UNAUTHORIZED", "error": "Missing or invalid API key"}403 — Phone is not verified or the key lacks permission (usually messages:create or api_keys:read).
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "FORBIDDEN", "error": "Phone not verified or missing permission"}429 — Rate limit exceeded. Honor Retry-After when present.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "RATE_LIMITED", "error": "Rate limit exceeded", "retryAfterSeconds": 30}HTTP request
POST /api/v2/verification/send
Request Headers
| Header | Type | Description |
|---|---|---|
| X-API-Key | string | Your Rasel API key. Send it on every documented request except inbound webhooks. * |
| Idempotency-Key | string | Optional unique key for safe retries. Takes precedence over a body idempotencyKey. Successful and failed responses can be replayed for 24 hours when send idempotency is enabled. |
Request body
| Field | Type | Description | Example |
|---|---|---|---|
| to | string | Recipient: E.164 phone, email when channel is email, WhatsApp group JID, Telegram chat id, or a string array of up to 100 recipients for an official batch. * | |
| channel | enum | Delivery channel. For unified send prefer auto, local_sms, int_sms, official_whatsapp, WhatsApp Web sessions, telegram_bot, or email_user. For verification omit the field for automatic selection; do not send bare sms, whatsapp, or auto. | |
| senderId | string | Approved SMS sender id. When omitted, the default then the platform sender is used. | |
| officialSenderId | string | Official WhatsApp sender id from /api/v2/official-senders. Alias of sender.officialId. Use platform for the default Meta number when listing templates. | |
| sender | object | Optional sender override. If omitted, Rasel uses the default approved sender, then the platform sender. | |
| sender.id | string | Approved SMS sender id. Leave it out to use the default sender. | |
| sender.officialId | string | Official WhatsApp sender id. Same as officialSenderId. | |
| idempotencyKey | string | Optional body alternative to the Idempotency-Key header. Prefer the header. |
Response Fields
| Field | Type | Description | Example |
|---|---|---|---|
| verificationId | string | Identifier returned from the verification send step. Prefer this on resend and verify. | |
| status | enum | Delivery or record status. On send: sent, queued, or scheduled. On other resources it is the row status filter or value. | |
| channel | string | Delivery channel. For unified send prefer auto, local_sms, int_sms, official_whatsapp, WhatsApp Web sessions, telegram_bot, or email_user. For verification omit the field for automatic selection; do not send bare sms, whatsapp, or auto. | |
| channels | string-list | Public channel names when send-on-all-compatible-channels fan-out succeeded on more than one channel. | |
| deliveries | json | Per-channel tracking when fan-out is enabled. | |
| expiresAt | string | When the current verification code expires. | |
| resendAvailableAt | string | Earliest time a resend is allowed. | |
| resendCount | number | How many times the code has been resent. |
Status Codes
| Status | Description |
|---|---|
| 200 | Success. |
| 400 | Invalid request, validation error, or the resource cannot be used in this state. |
| 401 | Missing or invalid API key. |
| 403 | Phone not verified, missing permission, or the account cannot perform this action. |
| 409 | Conflict, such as an idempotency key reuse with a different body, or a session that is not ready. |
| 429 | Rate limit exceeded, or the maximum number of verification attempts was reached. |
| 402 | Insufficient wallet balance or plan quota. |
Try it
This request may consume wallet balance or plan quota.
You are not signed in, or the server rejected this session. Lists stay empty until you sign in or enter a valid API key. Someone else's account is not shown.
Parameters
Optional unique key for safe retries. Takes precedence over a body idempotencyKey. Successful and failed responses can be replayed for 24 hours when send idempotency is enabled.
Delivery channel. For unified send prefer auto, local_sms, int_sms, official_whatsapp, WhatsApp Web sessions, telegram_bot, or email_user. For verification omit the field for automatic selection; do not send bare sms, whatsapp, or auto.
Recipient: E.164 phone, email when channel is email, WhatsApp group JID, Telegram chat id, or a string array of up to 100 recipients for an official batch.
Official WhatsApp sender id from /api/v2/official-senders. Alias of sender.officialId. Use platform for the default Meta number when listing templates.
Approved SMS sender id. When omitted, the default then the platform sender is used.
Optional body alternative to the Idempotency-Key header. Prefer the header.
Request
{}Response
Send a request to see the response.