Start here

Quickstart

Make your first email check at api.irondome.dev with a Bearer key. Read the result and handle invalid addresses, quota, and service errors.

On this page

Make a server-side email check with an API key and JSON. All requests use https://api.irondome.dev.

1. Create an API key

Create an account, then open API keys. Copy the full key when shown and save it as the server-side environment variable IRONDOME_API_KEY.

Keep keys out of browser code, source control, URLs, and logs. Your authorized plan determines quota and billing; the API origin is the same for every plan.

2. Check an email

With IRONDOME_API_KEY set, run curl in Bash, zsh, or another POSIX-compatible shell:

Terminal

curl --fail-with-body --request POST 'https://api.irondome.dev/v1/check' \
  --header "Authorization: Bearer $IRONDOME_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"email":"person@example.com"}'

A successful request returns HTTP 200. For example:

JSON

{
  "provider": "custom",
  "valid": true,
  "disposable": false,
  "reason": "not_listed"
}

The classification depends on the detection data. not_listed means no rule matched; it does not guarantee mailbox existence or delivery.

3. Apply the result

For disposable: true, ask for a permanent address or apply your signup policy.
For a successful disposable: false result, continue normal verification.
For HTTP 422 invalid_email, ask the user to correct the address.
For other failures, follow errors. An unavailable check is not a non-disposable result.

Each successfully classified address consumes one check, including disposable results.

Next steps

Choose an SDK and reuse its client. Use the Supabase Auth integration to screen user creation directly. Read plans and limits for free quota and bulk checks for lists.