Verify any email.
Catch fake addresses on signup.

# Didit Email Verification — integrate in 5 minutes

You are integrating Didit's Email Verification module into <my_stack>.
Follow these steps exactly. Every URL, header, and enum value below is
canonical — do not paraphrase or "improve" them. The module covers:
syntax validation, MX (Mail Exchange) lookup, SMTP (Simple Mail Transfer
Protocol) deliverability probe, disposable-provider detection,
free-provider detection, breach exposure lookup (HaveIBeenPwned-style),
catch-all + role-based anti-abuse signals, OTP (one-time password)
confirmation, and a configurable risk policy that can chain straight
into a Know Your Customer (KYC) (know your customer) workflow.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Two integration paths — pick one

### Path A — Workflow Builder (hosted UI)
Best when you want Didit to host the OTP entry screen, localize the
email template, handle resend cool-downs, and chain Email Verification
into a wider KYC / KYB workflow.

1. Create a workflow that contains the EMAIL_VERIFICATION feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array with the single entry
         { feature: "EMAIL_VERIFICATION" }   (UPPERCASE — strict enum)
   Optional config: per-warning action overrides (Decline / Review /
   Approve) for BREACHED_EMAIL_DETECTED, DISPOSABLE_EMAIL_DETECTED,
   DUPLICATED_EMAIL, and EMAIL_IN_BLOCKLIST.

2. Create a verification session for an end user:
   POST https://verification.didit.me/v3/session/
   Body: workflow_id (from step 1), vendor_data (your own user id),
   optional contact_details.email (pre-fills the OTP step).
   Response: session_url — redirect the user to it.

3. Listen for webhook callbacks (see "Webhooks" below).

### Path B — Standalone server-to-server API
Best when you already own the OTP UI and just want Didit to send and
validate the code plus return the risk signals.

Two endpoints, both authenticated with x-api-key:

POST https://verification.didit.me/v3/email/send/
Body (application/json):
  - email        (required, string — RFC 5322 address)
  - language     (optional, ISO 639-1 code — picks the email template)
  - vendor_data  (optional string, your user id)
Returns: { reference_id }

POST https://verification.didit.me/v3/email/check/
Body (application/json):
  - reference_id (required, from /email/send/)
  - code         (required, 6-digit string the user typed)
Returns: the full email-verification report (see Section 4).

Use the same vendor_data on retries so cross-session matches work.

## 3. Webhooks (Path A only — Path B returns synchronously)
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified",
                                  "session.review_started",
                                  "session.declined"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

Two module-level event types fire alongside the session events above:
- EMAIL_VERIFICATION_MESSAGE_SENT — OTP was dispatched
- EMAIL_VERIFICATION_DECLINED      — verification finished with a
                                     Declined status (caller should
                                     surface the warning to the user)

## 4. Reading the report (both paths return the same shape)
The email object includes:
- status: "Approved" | "Declined" | "In Review" | "Not Finished"
- email: the address that was verified
- is_breached: boolean — true when the address appears in known breaches
- breaches: array of { name, domain, logo_path, breach_date,
                       description, is_verified, data_classes,
                       breach_emails_count }
- is_disposable: boolean — true for throwaway providers
- is_undeliverable: boolean — true when MX + SMTP probe failed
- verification_attempts: number — OTP attempts used (max 2)
- verified_at: ISO 8601 timestamp
- matches: array of cross-session hits, each carrying session_id,
           session_number, vendor_data, verification_date, email,
           status, is_blocklisted
- warnings: Array<{ risk, additional_data, log_type,
                    short_description, long_description }>

Auto-decline risks (always enforced by Didit, not configurable):
- EMAIL_CODE_ATTEMPTS_EXCEEDED
- EMAIL_IN_BLOCKLIST
- UNDELIVERABLE_EMAIL_DETECTED

Configurable risks (action per workflow — Decline, Review, or Approve):
- BREACHED_EMAIL_DETECTED       (exposure / breach intelligence)
- DISPOSABLE_EMAIL_DETECTED     (temporary / throwaway provider)
- DUPLICATED_EMAIL              (cross-session match on another user)

Anti-abuse limits (enforced server-side):
- Code Entry Attempts: max 2 tries to type the right OTP
- Code Resend Requests: max 2 resends per 24 hours
- Code Validity: 5 minutes from delivery

## 5. Chaining Email Verification into a KYC flow
EMAIL_VERIFICATION is a regular feature inside the Workflow Builder, so
it composes with any of the 25+ other modules. The canonical patterns:

- Cheap pre-filter: gate KYC behind Email Verification so disposable +
  breached + undeliverable signups never burn a $0.33 KYC bundle. Use a
  conditional branch — if status is Declined on email, skip
  ID_VERIFICATION + LIVENESS + FACE_MATCH.
- Compliance log: keep Email Verification in the flow even when KYC is
  the primary check, so the verified email is timestamped and signed
  alongside the ID Verification report for Anti-Money Laundering (AML) (anti-money laundering)
  recordkeeping.
- Step-up auth: rerun Email Verification at a sensitive action (large
  withdrawal, password reset) using the same workflow + vendor_data
  for closed-loop continuity.

## 6. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: EMAIL_VERIFICATION, ID_VERIFICATION,
  LIVENESS, FACE_MATCH, AML, IP_ANALYSIS, PHONE_VERIFICATION.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Not Finished" (title-cased, space-separated).

## 7. Pricing reference (public)
- Email Verification: $0.03 per check (Path A or Path B).
- Bundled inside a full KYC workflow: same $0.03 add-on — the $0.33
  full-KYC bundle does not include EMAIL_VERIFICATION by default.
- 500 free checks every month, forever, on every account.

## 8. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test emails: deterministic synthetic addresses returned in sandbox
  (Approved by default; trigger Declined by sending the canonical
  disposable / breached test addresses listed in the docs).
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/email-verification/overview