Send instant OTP

Generates and sends OTP immediately over SMTP in request cycle.

POST/api/v1/instant-otp/send

Auth: Bearer public OTP token OR server API key with server_otp scope

Required headers

Header	Required	Value	Description
Authorization	Yes	Bearer <token>	API key, server OTP key, or public OTP token depending on endpoint.
Content-Type	Yes	application/json	All POST requests expect JSON payloads.

Request body

Field	Type	Required	Description
email	string	Yes	Target email.
from	string	No	From address override.
subject	string	No	OTP email subject.
verificationLine	string	No	Instruction line before code.
expiresInSeconds	number	No	60-3600, default 600.
otpDigits	number	No	4-10 digits, default 6.

Code examples (all supported languages)

Snippets use placeholder tokens. Replace them with real credentials from your dashboard.

curl -X POST "https://risumail.risu.in/api/v1/instant-otp/send" \
  -H "Authorization: Bearer risu_otp_PUBLIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","expiresInSeconds":600,"otpDigits":6}'

Response schema

Canonical schema inferred from the documented success payload. Copy this block when generating typed clients.

{
  "type": "object",
  "required": [
    "success",
    "data"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    },
    "data": {
      "type": "object",
      "required": [
        "sessionId",
        "expiresAt",
        "email",
        "sent"
      ],
      "properties": {
        "sessionId": {
          "type": "string"
        },
        "expiresAt": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "sent": {
          "type": "boolean"
        }
      }
    }
  }
}

Success response example

{
  "success": true,
  "data": {
    "sessionId": "otp_sess_01J...",
    "expiresAt": "2026-04-19T11:50:00.000Z",
    "email": "user@example.com",
    "sent": true
  }
}

Common error cases

Status	Code	When
403	OTP_PUBLIC_IP_NOT_ALLOWED	Public token IP allowlist blocked.
429	OTP_RATE_LIMITED	OTP send rate limit exceeded.
503	SMTP_NOT_CONFIGURED	No usable SMTP route.

Implementation notes

Public tokens enforce allowlist on send.
Prefer instant-otp routes for browser and edge integrations.

Back to API reference index Error handling playbook