Email OTP integration

Use this guide when you want OTP.ID to deliver an OTP to an email address. Send channel: "email" to POST /v3/request or POST /v3/send, then verify the user-entered code with POST /v3/verify. Email OTP fits email-first registration, account recovery, and desktop flows. OTP.ID includes your brand in the email subject and body. If your merchant account has a brand_logo, OTP.ID also displays it in the email.

Flow overview

Create the OTP transaction

Use POST /v3/request for an OTP.ID-generated code, or POST /v3/send when your backend generates the code.

OTP.ID sends the email

OTP.ID sends an HTML email to the destination address.

Collect the code

Ask the user to copy the code from the email. If needed, remind them to check spam or junk.

Verify the code

Call POST /v3/verify with the otp_id and submitted code.

Email branding

Field	Behavior
`brand`	Shown in the email subject and body. If omitted, OTP.ID uses the `brand_name` configured on your merchant account.
Merchant `brand_logo`	Optional HTTPS image URL configured on your merchant account. When present and valid, OTP.ID displays it in the Email OTP template. When omitted or invalid, the logo area is hidden so the email remains clean.

The Email OTP request payload does not need a logo field. Configure the logo on your merchant account, and OTP.ID applies it automatically for Email OTP.

Option A: OTP.ID generates the code

Request

curl -X POST https://api.otp.id/v3/request \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "destination": "user@example.com",
    "brand": "TokoKita",
    "otp_length": 6
  }'

Success response

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811MAIL000001",
    "status": "sent",
    "channel": "email",
    "number": "user@example.com",
    "price": 125,
    "last_balance": 99875,
    "expires_at": "2026-08-11 10:05:00"
  },
  "error": null
}

The generated OTP code is not returned by the API. OTP.ID sends it only to the user’s email inbox.

Option B: You provide the code

Request

curl -X POST https://api.otp.id/v3/send \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "destination": "user@example.com",
    "otp": "482913",
    "brand": "TokoKita"
  }'

Success response

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811MAIL000002",
    "status": "sent",
    "channel": "email",
    "number": "user@example.com",
    "price": 125,
    "last_balance": 99750,
    "expires_at": "2026-08-11 10:05:00"
  },
  "error": null
}

Verify the Email OTP

Request

curl -X POST https://api.otp.id/v3/verify \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "otp_id": "OTP20260811MAIL000001",
    "otp": "482913"
  }'

Correct code response

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811MAIL000001",
    "verified": true,
    "reason": ""
  },
  "error": null
}

Wrong code response

Wrong codes return HTTP 200. Always check data.verified.

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811MAIL000001",
    "verified": false,
    "reason": "mismatch"
  },
  "error": null
}

Terminal error example

{
  "success": false,
  "data": null,
  "error": {
    "code": "ALREADY_USED",
    "message": "OTP sudah pernah diverifikasi"
  }
}

UI recommendations

Show copy such as “Enter the code we sent to user@example.com.”
Mask long email addresses where appropriate, for example u•••@example.com.
Include a Check spam or junk folder hint after a short delay.
Keep the resend action visible but disabled until cooldown completes.
If the user changes their email address, create a new OTP transaction.
Do not ask users to forward the OTP email or send screenshots of it.

Get Started

Core Concepts

Channel Guides

Guides

Reference

Email OTP integration

Flow overview

Email branding

Option A: OTP.ID generates the code

Request

Success response

Option B: You provide the code

Request

Success response

Verify the Email OTP

Request

Correct code response

Wrong code response

Terminal error example

UI recommendations

​Flow overview

​Email branding

​Option A: OTP.ID generates the code

​Request

​Success response

​Option B: You provide the code

​Request

​Success response

​Verify the Email OTP

​Request

​Correct code response

​Wrong code response

​Terminal error example

​UI recommendations

​Related pages

Flow overview

Email branding

Option A: OTP.ID generates the code

Request

Success response

Option B: You provide the code

Request

Success response

Verify the Email OTP

Request

Correct code response

Wrong code response

Terminal error example

UI recommendations

Related pages