Introduction

OTP Verification lets you send one-time codes to a phone number or email address, then check the code your user enters. You can send codes by SMS, voice call, WhatsApp, Telegram, or email.

How it works

1. Create a verification with a sender profile, channel, and destination.
2. Maileroo generates the code and starts delivery in the background. The create request returns 202 Accepted; the code is not included in the response.
3. Ask your user for the code and send it to the check endpoint.
4. Use the check result and verification status to decide whether to continue.

Codes are generated by the service. code_length can be from 4 to 8 digits and defaults to 6. For phone channels, to must be a valid phone number in E.164 format, including its country calling code. For email, provide an email address.

Base URL

All endpoints use this base URL:

https://api.maileroo.com/v1/verify

Authentication

Authenticate each request with an API key in the Authorization header as a Bearer token:

Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Use a key with the scope required by the endpoint. A key can have more than one scope:

Requests and responses

Send JSON requests with Content-Type: application/json. Successful responses contain a top-level data property:

{
  "data": {
    "id": "vrf_0123456789abcdef01234567"
  }
}

GET /verifications returns its results as data.items, with next_cursor and total. Successful deletes return 204 No Content with an empty body.

Errors use a non-2xx status and this shape:

{
  "error": {
    "message": "Your OTP Verification balance is too low. Add funds and try again."
  }
}

The Account API allows 180 requests per minute per account. Common errors include 401 Unauthorized for missing or invalid authentication, 403 Forbidden for a missing scope or account restriction, 429 Too Many Requests for a rate limit, 500 Internal Server Error for an unexpected failure, 502 Bad Gateway when OTP Verification cannot be reached, and 503 Service Unavailable when OTP Verification or billing is unavailable. Creating a verification can also return 429 when its sender profile's rate limit is reached.

Idempotency

POST /verifications accepts an optional Idempotency-Key header. Reusing the same key for the same account returns the existing verification instead of creating a duplicate. Keys may contain up to 200 printable ASCII characters. This header is honored only when creating a verification.

Billing

Sends use the prepaid OTP Verification balance, which you can add funds to in the dashboard under OTP Verification → Usage & Billing. When you submit a create request, a temporary hold is placed on the balance before delivery begins. The hold is then reconciled to the actual delivery cost, which can take up to 48 hours. A separate verification fee is charged when a code is checked successfully.

If the balance cannot cover a send, the API returns 402 Payment Required with the message shown above. See Maileroo pricing for pricing information.

Verification history is retained for 120 days.

API reference

• Verifications — send, check, list, and cancel codes.
• Sender profiles — configure names, channels, and rate limits.
• Webhooks — receive verification events.