Send OTP

Send one-time passwords (OTPs) via Email, SMS, or WhatsApp for user verification, 2FA, and authentication workflows.

Endpoint

POST /api/v1/otp/send

Headers

X-API-Key: sk_live_your_api_key
Content-Type: application/json

Why Use This Endpoint?

🔐 Multi-Channel - Send OTP via Email, SMS, WhatsApp, or all three simultaneously
⚡ Instant Delivery - Fast OTP generation and delivery across all channels
🎯 Flexible Configuration - Customize OTP length, expiry time, and attempt limits
🧪 Sandbox Testing - Test without sending real messages or charges
📊 Session Management - Built-in tracking, rate limiting, and security
🔄 Auto-Contact Sync - Optionally create contacts when they verify

Core Concept

An OTP session is created when you send an OTP. The session manages:

OTP codes for each channel (hashed for security)
Verification status for each channel
Security settings (expiry, max attempts, rate limiting)
Custom metadata for your application logic

After sending, you receive a session token that you'll use to verify the OTP later.

Request Structure

Required Fields

Field	Type	Description
`channels`	array	Array of channels: `"email"`, `"sms"`, `"whatsapp"`
`recipients`	object	Recipient contact for each channel

Recipients Object

Field	Type	Required When	Description
`recipients.email`	string	`channels` includes `"email"`	Valid email address
`recipients.sms`	string	`channels` includes `"sms"`	Phone number in E.164 format (+1234567890)
`recipients.whatsapp`	string	`channels` includes `"whatsapp"`	WhatsApp number in E.164 format

Optional Fields

Field	Type	Default	Description
`config`	object	See below	OTP configuration settings
`metadata`	object	`{}`	Custom data to store with session
`add_contact`	boolean	`false`	Create contact after successful verification
`sandbox_mode`	boolean	`false`	Test mode - returns OTPs, doesn't send messages

Configuration Object (`config`)

Field	Type	Default	Description
`otp_length`	number	6	OTP code length (4-8 digits)
`expiry_minutes`	number	10	Session expiry time
`max_attempts`	number	3	Maximum verification attempts

Use Case Examples

Example 1: Email Verification

Send OTP to verify a user's email address during registration.

curl -X POST https://api.sendmator.com/api/v1/otp/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": ["email"],
    "recipients": {
      "email": "newuser@example.com"
    },
    "config": {
      "otp_length": 6,
      "expiry_minutes": 10
    },
    "metadata": {
      "purpose": "email_verification",
      "user_id": "user_12345"
    },
    "add_contact": true
  }'

Response:

{
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "channels_sent": {
    "email": {
      "success": true,
      "message_id": "msg_550e8400e29b41d4a716446655440000"
    }
  },
  "expires_at": "2024-01-15T10:45:00.000Z",
  "verification_mode": "any"
}

Example 2: Phone Verification (SMS + WhatsApp)

Send OTP to both SMS and WhatsApp, allowing the user to verify via either channel.

curl -X POST https://api.sendmator.com/api/v1/otp/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": ["sms", "whatsapp"],
    "recipients": {
      "sms": "+1234567890",
      "whatsapp": "+1234567890"
    },
    "config": {
      "otp_length": 6,
      "expiry_minutes": 5
    },
    "metadata": {
      "purpose": "phone_verification",
      "user_id": "user_67890"
    }
  }'

Response:

{
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "channels_sent": {
    "sms": {
      "success": true,
      "message_id": "msg_660f9511f30c52e5b827557766551111"
    },
    "whatsapp": {
      "success": true,
      "message_id": "msg_660f9511f30c52e5b827557766552222"
    }
  },
  "expires_at": "2024-01-15T10:40:00.000Z",
  "verification_mode": "any"
}

Example 3: Two-Factor Authentication (2FA)

Send a short-lived OTP for 2FA during login.

curl -X POST https://api.sendmator.com/api/v1/otp/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": ["sms"],
    "recipients": {
      "sms": "+1234567890"
    },
    "config": {
      "otp_length": 6,
      "expiry_minutes": 5,
      "max_attempts": 3
    },
    "metadata": {
      "purpose": "2fa_login",
      "user_id": "user_12345",
      "ip_address": "192.168.1.1"
    }
  }'

Response:

{
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "channels_sent": {
    "sms": {
      "success": true,
      "message_id": "msg_770g0622g41d63f6c938668877662222"
    }
  },
  "expires_at": "2024-01-15T10:40:00.000Z",
  "verification_mode": "any"
}

Example 4: Multi-Channel Verification

Send OTP to all three channels for maximum delivery success.

curl -X POST https://api.sendmator.com/api/v1/otp/send \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": ["email", "sms", "whatsapp"],
    "recipients": {
      "email": "user@example.com",
      "sms": "+1234567890",
      "whatsapp": "+1234567890"
    },
    "config": {
      "otp_length": 6,
      "expiry_minutes": 10
    },
    "metadata": {
      "purpose": "account_verification"
    }
  }'

Response:

{
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "channels_sent": {
    "email": {
      "success": true,
      "message_id": "msg_880h1733h52e74g7d049779988773333"
    },
    "sms": {
      "success": true,
      "message_id": "msg_880h1733h52e74g7d049779988774444"
    },
    "whatsapp": {
      "success": true,
      "message_id": "msg_880h1733h52e74g7d049779988775555"
    }
  },
  "expires_at": "2024-01-15T10:45:00.000Z",
  "verification_mode": "any"
}

Example 5: Sandbox Mode (Testing)

Test OTP flow without sending real messages or incurring charges.

curl -X POST https://api.sendmator.com/api/v1/otp/send \
  -H "X-API-Key: sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": ["email", "sms"],
    "recipients": {
      "email": "test@example.com",
      "sms": "+1234567890"
    },
    "sandbox_mode": true
  }'

Response (Sandbox Mode):

{
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "channels_sent": {
    "email": {
      "success": true,
      "message_id": "msg_sandbox_990i2844i63f85h8e150880099884444"
    },
    "sms": {
      "success": true,
      "message_id": "msg_sandbox_990i2844i63f85h8e150880099885555"
    }
  },
  "sandbox_otps": {
    "email": "123456",
    "sms": "123456"
  },
  "expires_at": "2024-01-15T10:45:00.000Z",
  "verification_mode": "any"
}

Response Fields

Success Response

Field	Type	Description
`session_token`	string	JWT token for verifying OTP later
`channels_sent`	object	Status of each channel send attempt
`expires_at`	string	ISO 8601 timestamp when session expires
`verification_mode`	string	Verification mode: `"any"` or `"all"`
`sandbox_otps`	object	OTP codes (only in sandbox mode)

Channels Sent Object

Each channel in channels_sent contains:

Field	Type	Description
`success`	boolean	Whether the OTP was sent successfully
`message_id`	string	Unique message identifier for tracking

Error Response

{
  "statusCode": 400,
  "message": "Invalid recipient email address",
  "error": "Bad Request"
}

Common Error Responses

Status Code	Error	Cause
400	Invalid recipient	Email/phone format is incorrect
400	Invalid channel	Channel not supported
400	Missing recipients	Recipients object missing required fields
401	Invalid API key	API key is missing or incorrect
402	Insufficient balance	Not enough wallet credits
429	Rate limit exceeded	Too many OTP requests

Recipient Format Validation

Email

Must be a valid email address
Example: user@example.com

Phone Number (SMS/WhatsApp)

Must be in E.164 format
Include country code with + prefix
No spaces, dashes, or parentheses
Examples:
- ✅ +1234567890 (US)
- ✅ +919876543210 (India)
- ✅ +442071234567 (UK)
- ❌ 1234567890 (missing + and country code)
- ❌ +1 (234) 567-8900 (contains formatting)

Best Practices

1. Security

Store the token securely on the client side
Never log or expose OTP codes in production
Use short expiry times (5-10 minutes) for sensitive operations
Implement rate limiting on your application side
Monitor failed attempts and block suspicious activity

2. User Experience

Clear instructions - Tell users where to find the OTP
Multiple channels - Offer SMS + WhatsApp for better deliverability
Resend option - Allow users to request a new OTP
Show expiry time - Display countdown timer
Error handling - Provide helpful error messages

3. Configuration

OTP length: Use 6 digits for balance of security and usability
Expiry time:
- 5 minutes for 2FA/login
- 10 minutes for verification workflows
- 15 minutes for password resets
Max attempts: 3 attempts is recommended

4. Metadata Usage

Store context for later retrieval:

{
  "metadata": {
    "user_id": "user_12345",
    "purpose": "email_verification",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0...",
    "app_version": "2.1.0"
  }
}

5. Auto-Contact Creation

Enable add_contact: true to automatically add verified users to your contacts:

{
  "add_contact": true
}

This creates a contact record when the user successfully verifies any channel.

Rate Limits

To prevent abuse:

5 OTP sends per 5 minutes per user
20 OTP sends per hour per IP address
100 active sessions per user

Sandbox vs Production

Feature	Sandbox Mode	Production Mode
Messages Sent	❌ No	✅ Yes
OTPs Returned	✅ Yes	❌ No
Wallet Charged	❌ No	✅ Yes
Use Case	Testing	Live users

Next Steps

Verify OTP - Learn how to verify OTP codes
OTP Overview - Understand OTP concepts
Authentication - Set up API keys

Endpoint​

Headers​

Why Use This Endpoint?​

Core Concept​

Request Structure​

Required Fields​

Recipients Object​

Optional Fields​

Configuration Object (config)​

Use Case Examples​

Example 1: Email Verification​

Example 2: Phone Verification (SMS + WhatsApp)​

Example 3: Two-Factor Authentication (2FA)​

Example 4: Multi-Channel Verification​

Example 5: Sandbox Mode (Testing)​

Response Fields​

Success Response​

Channels Sent Object​

Error Response​

Common Error Responses​

Recipient Format Validation​

Email​

Phone Number (SMS/WhatsApp)​

Best Practices​

1. Security​

2. User Experience​

3. Configuration​

4. Metadata Usage​

5. Auto-Contact Creation​

Rate Limits​

Sandbox vs Production​

Next Steps​

Endpoint

Headers

Why Use This Endpoint?

Core Concept

Request Structure

Required Fields

Recipients Object

Optional Fields

Configuration Object (`config`)

Use Case Examples

Example 1: Email Verification

Example 2: Phone Verification (SMS + WhatsApp)

Example 3: Two-Factor Authentication (2FA)

Example 4: Multi-Channel Verification

Example 5: Sandbox Mode (Testing)

Response Fields

Success Response

Channels Sent Object

Error Response

Common Error Responses

Recipient Format Validation

Email

Phone Number (SMS/WhatsApp)

Best Practices

1. Security

2. User Experience

3. Configuration

4. Metadata Usage

5. Auto-Contact Creation

Rate Limits

Sandbox vs Production

Next Steps