Send Verification
Create a verification and start sending its generated code.
Create a verification and start sending its generated code in the background. The code is never returned in the response.
Scope: verify.verifications.write
Request Body
sender_profile_idstringrequiredThe sender profile to use, for example prf_0123456789abcdef01234567.
channelstringrequiredOne of sms, voice, whatsapp, telegram, or email. The channel must be enabled on the sender profile.
tostringrequiredA valid phone number in E.164 format for phone channels, or an email address for email.
code_lengthintegeroptionalGenerated code length from 4 to 8 digits. If omitted, the default length is 6.
expires_inintegeroptionalVerification lifetime in seconds, from 180 to 86400. If omitted, the service applies its current expiration setting.
Headers
Idempotency-KeystringoptionalOptional key honored only by this create endpoint. Repeating the key for the same account returns the existing verification. The key can contain up to 200 printable ASCII characters.
Sample Request
curl -X POST "https://api.maileroo.com/v1/verify/verifications" \
-H "Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: signup-42" \
-H "Content-Type: application/json" \
-d '{"sender_profile_id":"prf_0123456789abcdef01234567","channel":"sms","to":"+61412345678","code_length":6,"expires_in":900}'Sample Response
Returns 202 Accepted. The delivery continues in the background.
{
"data": {
"id": "vrf_0123456789abcdef01234567",
"account_id": "12345",
"sender_profile_id": "prf_0123456789abcdef01234567",
"channel": "sms",
"to": "+61412345678",
"country": "AU",
"code_length": 6,
"status": "pending",
"attempts": 0,
"max_attempts": 3,
"expires_at": "2025-01-01T12:15:00Z",
"created_at": "2025-01-01T12:00:00Z",
"updated_at": "2025-01-01T12:00:00Z"
}
}The max_attempts value above is illustrative; the response reports the applicable value.
Errors
Common authentication, rate-limit, and service-availability errors are described in the Introduction. This endpoint can also return:
400 Bad Request— invalid JSON or request values, including an invalid code length, expiration, or idempotency key.402 Payment Required— the prepaid balance is too low. The message isYour OTP Verification balance is too low. Add funds and try again.404 Not Found— the sender profile does not exist for this account.422 Unprocessable Entity— the channel is not enabled for the sender profile or the request cannot be fulfilled.429 Too Many Requests— the sender profile's destination or profile rate limit was reached.503 Service Unavailable— billing is temporarily unavailable.