Skip to main content
POST
curl

Authorizations

x-api-key
string
header
required

Body

application/json
email
string<email>
required

Recipient email address. Malformed addresses return 400; syntactically valid addresses that cannot receive mail (failed DNS/MX validation) return 200 with status: "Undeliverable".

Example:

"alice@example.com"

options
object

OTP format, localization, and branding options. All fields are optional.

signals
object

Optional device and network signals about the end user, forwarded to the anti-fraud layer to improve detection of abusive or automated traffic. All fields are optional.

vendor_data
string

Optional caller-controlled identifier (your internal user id, an email, a UUID, etc.) persisted on the session and echoed back in the send response, the matching check response, webhooks, and the Business Console. Use it to correlate Didit's request_id with your user record.

metadata
object | null

Optional free-form JSON object persisted on the session and echoed back in the send response, the matching check response, webhooks, and the Business Console.

Response

Send acknowledged. Inspect status: Success and Retry mean a code is on its way; Undeliverable means the address cannot receive mail and the verification is already finalized as Declined. request_id is the persisted session id (same id on a Retry).

request_id
string<uuid>

Session id of the verification. A Retry send returns the same request_id as the original send. This id appears in the Business Console, is returned again by a finalized POST /v3/email/check/, and can be passed to GET /v3/session/{sessionId}/decision/.

status
enum<string>

Success — OTP emailed to a new verification (billed). Retry — fresh OTP emailed for the pending verification created by a previous send (free). Undeliverable — the address failed deliverability validation or the message could not be sent; the verification is immediately finalized as Declined and nothing is billed.

Available options:
Success,
Retry,
Undeliverable
reason
enum<string> | null

email_can_not_be_delivered when status is Undeliverable; null otherwise.

Available options:
email_can_not_be_delivered,
null
vendor_data
string | null

Echo of the vendor_data stored on the session (from the first send).

metadata
object | null

Echo of the metadata stored on the session (from the first send).