Block disposable emails in your signup flow

Where the check belongs

Validate the email in your backend before creating the account or sending an ownership-verification email. The browser submits to your existing signup handler; the handler calls IronDome with a private key.

Do not call IronDome on every keystroke. Check after the user submits a complete address, or at a deliberate validation step. If you check earlier in the browser flow, the final backend handler still needs to enforce its own decision.

For the request body and response fields, use the email-check API reference. Start with the Node.js example or Python example for your backend. If Supabase Auth creates your users, use the Before User Created hook instead of relying on a browser-only precheck.

Handle each outcome

Outcome	Signup action	Suggested message
HTTP 200, disposable: false	Continue to ownership verification	No additional message needed
HTTP 200, disposable: true	Ask for another address	Please use a permanent email address.
HTTP 422, invalid_email	Keep the form open	Enter a valid email address.
HTTP 429	Stop the check and handle your allowance	Email checks are temporarily unavailable. Please try again later.
Timeout or service failure	Offer a retry without accepting a fabricated result	We couldn't check your email. Please try again.
HTTP 401 or 403	Fix backend configuration	Use the generic unavailable message for customers

Keep the user's other form values when showing an email error. Display it next to the email field and associate it with aria-describedby. Do not expose API keys or internal error details to the customer.

Test the signup decision before release

Use stubbed API responses in application tests. Verify that disposable: true asks for another address without creating an account or sending a verification email. Verify that disposable: false continues to your normal ownership-verification flow. For invalid input, quota errors, authentication failures and timeouts, confirm that the handler follows the unavailable or correction path in the table rather than treating the error as a non-disposable result.

Do not automatically retry a timed-out check. It may already have completed and counted toward usage. See the API failure guidance.

Keep signup fast

Use one reusable server-side client. You can optionally prepare its connection when the page loads, while the customer fills the form. See performance and warmup.

Overlap a check only with independent work that does not create an account, send an OTP, or charge the customer. Wait for your email decision before those actions.

Ownership and abuse controls

A non-disposable result does not prove that the customer owns the mailbox. Complete your verification-code or verification-link flow separately.

Retain your existing signup rate limits and abuse controls. IronDome classifies email addresses; it is not a replacement for application authentication or bot protection.