Email OTP API

Getting Started

The Email OTP API provides two main operations: sending a one-time password and verifying the OTP received by the user.

API Base URL

All API endpoints are available under:

/api/v1/

Email OTP endpoints:

/api/v1/email/send.php
/api/v1/email/verify.php

Send OTP

Send a one-time password to an email address.

Content-Type: application/json

{
    "to": "user@example.com",
    "name": "John",
    "length": "6",
    "format": "N"
}

3
4
6
8

{
    "status": true,
    "message": "OTP sent successfully."
}

{
    "status": false,
    "message": "Error message."
}

Verify OTP

Verify the OTP sent to an email address.

Content-Type: application/json

{
    "to": "user@example.com",
    "otp": "583214"
}

{
    "status": true,
    "message": "OTP verified successfully."
}

{
    "status": false,
    "message": "Invalid OTP."
}

Validation

The API validates the email address, OTP and OTP configuration before processing the request.

• Recipient email is required.
• Recipient email must be valid.
• OTP length is required for OTP generation.
• OTP length must be between 3 and 8.
• OTP is required during verification.
• Invalid OTP values are rejected.

OTP Expiration

An OTP is temporary and can only be used within its valid lifetime.

After successful verification, the stored OTP is removed and cannot be verified again. Expired OTP records are also removed when they are detected during verification.

JavaScript Integration

The API can be called directly from JavaScript using fetch().

Send OTP

async function sendOtp() {
    const response = await fetch("/api/v1/email/send.php", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            to: "user@example.com",
            name: "John",
            length: "6",
            format: "N"
        })
    });

    const data = await response.json();
    console.log(data);
}

Verify OTP

async function verifyOtp() {
    const response = await fetch("/api/v1/email/verify.php", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            to: "user@example.com",
            otp: "583214"
        })
    });

    const data = await response.json();
    console.log(data);
}

PHP Integration

The API can also be integrated from a PHP application.

Send OTP

$data = [
    "to" => "user@example.com",
    "name" => "John",
    "length" => "6",
    "format" => "N"
];

$ch = curl_init("/api/v1/email/send.php");

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

Verify OTP

$data = [
    "to" => "user@example.com",
    "otp" => "583214"
];

$ch = curl_init("/api/v1/email/verify.php");

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

Complete Integration Flow

1. Collect Email: Ask the user for their email address.
2. Send OTP: Send a request to POST /api/v1/email/send.php.
3. User Receives OTP: The user receives the generated OTP at their email address.
4. Collect OTP: Ask the user to enter the received OTP.
5. Verify OTP: Send the email and OTP to POST /api/v1/email/verify.php.
6. Check Response: Continue only when the returned status is true.

API Response Format

API responses use JSON. Successful and failed responses use the same basic structure.

{
    "status": true,
    "message": "..."
}

{
    "status": false,
    "message": "..."
}

Applications should check the status value before continuing with the next step.

Endpoint Reference

Quick Example

POST /api/v1/email/send.php
Content-Type: application/json

{
    "to": "user@example.com",
    "name": "John",
    "length": "6",
    "format": "N"
}

POST /api/v1/email/verify.php
Content-Type: application/json

{
    "to": "user@example.com",
    "otp": "583214"
}