Skip to main content
POST
/
api
/
v1
/
send
Send Verification Code
curl --request POST \
  --url https://app.easyotp.dev/api/v1/send \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '{
  "channel": "<string>",
  "recipient": "<string>",
  "message": "<string>",
  "subject": "<string>",
  "expires_in": 123,
  "code": "<string>"
}'
{
  "error": "channel is required and must be one of: sms, email, voice",
  "request_id": "7b4d6022-7260-4568-b6b7-29c366c47bbc"
}

​
Request

Send a one-time password to a recipient via your chosen channel.

​
Headers

​
Authorization
string
required
Bearer token with your API key: Bearer YOUR_API_KEY
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
channel
string
required
Communication channel for the verification code. Must be one of: sms, email, or voice
​
recipient
string
required
Recipient address:
  • For SMS/Voice: E.164 formatted phone number (e.g., +1234567890)
  • For Email: Valid email address (e.g., [email protected])
​
message
string
Custom message template. Use {code} as a placeholder for the verification code.Default: "Your verification code is: {code}"Example: "Your Acme Corp verification code is: {code}. Valid for 5 minutes."
​
subject
string
Email subject line (only used when channel is email)Default: "Your Verification Code"Example: "Verify Your Acme Corp Account"
​
expires_in
integer
Code expiration time in seconds. Must be between 60 and 3600.Default: 300 (5 minutes)
​
code
string
Custom verification code. Must be a numeric string between 4-10 digits.If not provided, a code will be automatically generated with a length defined in your account settings.Example: "123456"

​
Response

​
success
boolean
Always true for successful requests
​
verification_id
string
Unique identifier for this verification. Use this when calling the verify endpoint.Example: "11f951d5-32d1-4b49-bdda-7da248e2615c"
​
expires_at
string
ISO 8601 timestamp when the code expiresExample: "2024-01-01T12:05:00.000Z"
​
request_id
string
Unique request identifier for debuggingExample: "7b4d6022-7260-4568-b6b7-29c366c47bbc"

​
Examples

curl -X POST https://app.easyotp.dev/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "recipient": "+1234567890",
    "message": "Your verification code is: {code}",
    "expires_in": 300
  }'

​
Success Response

{
  "success": true,
  "verification_id": "11f951d5-32d1-4b49-bdda-7da248e2615c",
  "expires_at": "2024-01-01T12:05:00.000Z",
  "request_id": "7b4d6022-7260-4568-b6b7-29c366c47bbc"
}

​
Error Responses

{
  "error": "channel is required and must be one of: sms, email, voice",
  "request_id": "7b4d6022-7260-4568-b6b7-29c366c47bbc"
}

​
Rate Limiting

This endpoint enforces per-recipient rate limits to prevent spam and abuse:
  • 2 sends per minute per recipient
  • 15 sends per hour per recipient
  • 50 sends per 24 hours per recipient
When you exceed these limits, you’ll receive a 429 response with a retry_after field indicating how many seconds until you can retry.
In addition to per-recipient limits, API keys are also rate limited to 120 requests per minute across all endpoints. Test recipients (like +15555550100) are exempt from per-recipient limits but still count toward your API key limits. See the Rate Limits section for more details.

​
Best Practices

Keep messages clear and branded: Include your app name in the message so users know where the code is coming from.Good: "Your Acme Corp verification code is: {code}"Bad: "{code}"
Set appropriate expiration times:
  • SMS/Voice: 2-5 minutes (users typically verify immediately)
  • Email: 10-15 minutes (users may need to open their email client)
Phone number format: Phone numbers must be in E.164 format (starting with + and country code). Invalid formats will be rejected.
Message length limits:
  • SMS: 160 characters recommended
  • Email: No hard limit, but keep it concise
  • Voice: Keep under 50 characters for best experience

​
Credits Consumed

Each send request consumes 1 credit regardless of the channel:
ChannelCredits
SMS1 credit
Email1 credit
Voice1 credit
Failed sends do not consume credits.