Integrate with an AI Agent

Use your coding agent to add DISIFY to an existing email validation flow. Core checks need no account or API key.

Choose Copy integration prompt and paste it into your agent. Copy as Markdown includes the complete guide and test cases.

Preview the integration prompt

Integrate DISIFY into this application's existing email validation flow.

Read https://docs.disify.com/guide/agents.md. Find supporting docs at https://docs.disify.com/llms.txt and the API contract at https://docs.disify.com/openapi.yaml.

Inspect the existing validation flow, HTTP client, and tests. Follow the application's conventions and reuse its HTTP client.

Call POST https://disify.com/api/email from the backend with a form-encoded email parameter, preserving literal + characters. Set a timeout and disable redirects. Core checks work anonymously. If using a key, read DISIFY_API_KEY from server configuration and send X-Api-Key. Keep the key out of frontend code, source control, prompts, and logs.

Check HTTP status and response types before reading validation fields. Handle invalid format, disposable addresses, inconclusive DNS, rate limits, quota exhaustion, and service failures. Preserve the existing policy for unavailable checks; if none exists, ask whether to allow provisionally, hold for retry, or reject. An unavailable check must never be reported as a successful validation.

Use disposable as the disposable verdict; whitelist does not override it. If the integration uses a paid privacy-relay policy, also require blocked === false; null or missing is not an allow verdict. Honor returned policy rejections even when disposable is false. Never replace an individual email check with a domain verdict or strip plus tags before validation. Keep any existing email ownership verification.

Add mocked tests using the guide's cases. Report the changes, tests, required configuration, and rejection/unavailability policy.

Make the request

Use a form-encoded POST to keep addresses out of URLs. Let your HTTP client encode the form so literal + characters survive.

curl --fail-with-body --max-time 10 \
  https://disify.com/api/email \
  --data-urlencode 'email=user+tag@gmail.com'

The Quick Start has Python, JavaScript, and PHP examples with error handling. For a bare domain, use POST /api/domain with a domain form parameter.

For authenticated access, use X-Api-Key or Authorization: Bearer and keep the key on the server. See Authentication and Premium Features.

Check at form submission or the existing validation step, not on every keystroke. Set a timeout, disable redirects, and bound retries. The example's 10-second timeout is a client setting, not a response-time guarantee.

Interpret the result

First check HTTP status, parse JSON, and verify that the response has the expected types. Then apply your application's policy:

Result	Meaning and integration behavior
format: false	Invalid syntax. Other validation fields can be absent; request a corrected address.
disposable: true	Disposable detection is positive. Apply the application's rejection or review policy.
blocked: true	The paid validation settings reject the address, including a privacy relay with disposable: false. Honor this rejection.
blocked: null, or missing when enforcing relay rejection	The relay rejection decision is unavailable. Apply the application's unavailable-check policy.
signals includes dns_indeterminate	DNS was inconclusive. Do not interpret dns: false as confirmed absence of mail servers; retry later if DNS matters to your decision. Other completed checks still apply.
dns: false without dns_indeterminate	The check did not find usable mail DNS. Apply your application's DNS policy.
format: true, disposable: false, dns: true	Core checks passed. This does not establish mailbox existence, ownership, or guaranteed delivery; retain email verification where required.
Missing or incorrectly typed decision fields in an otherwise valid-format response	Unexpected response. Treat the check as unavailable, not as a safe address.

Optional alias, whitelist, and signals can be absent. A missing disposable in a valid-format response is an error, not a negative verdict. See Response Fields and Privacy Forwarding for paid settings and decisions.

Use disposable as the disposable verdict; neither whitelist nor a reconstructed confidence threshold should override it by default. Preserve plus tags and Gmail dots so per-email detection can use them.

Handle unavailable checks

• For per-minute 429 responses, respect Retry-After / retry_after. For daily or monthly quota exhaustion, use reset_at instead of retrying repeatedly.
• For 503, use any provided retry guidance, bounded attempts, and jitter. Treat timeouts, malformed responses, and other service failures as unavailable.
• Invalid keys (401) and denied access (403) require configuration or account attention, not repeated retries.
• Requested fields listed in temporarily_unavailable_features should be retried later. requires_upgrade and unsupported_features have different meanings and should not trigger automatic retries.

Apply the application's unavailable-check policy. See Error Handling and Rate Limits.

Cache and batch carefully

Domain checks cannot detect individual mailbox or plus-alias abuse. Keep per-email checks, including on Gmail, Outlook, and iCloud. If caching email results, include the full input, requested features, API-key context, and request overrides. Invalidate when the plan or account/key settings change, set an expiry, and exclude errors and inconclusive results.

For imports, use Bulk Validation and handle both synchronous and queued responses. json=1 includes per-entry results only on synchronous completion. Poll queued sessions from the submitting backend; inspect the content type because completion normally returns a plain-text valid list. Retrieve results within 15 minutes. Avoid resubmitting a batch after an ambiguous timeout.

Test the integration

Mock HTTP responses in automated tests; do not rely on live address verdicts or spend API quota.

Fixture	Expected integration behavior
200, {"format":true,"disposable":false,"dns":true}	Core checks pass.
200, {"format":true,"disposable":true,"dns":true}	Disposable policy applies.
200, {"format":true,"disposable":false,"dns":true,"blocked":true}	Paid privacy-relay policy rejects independently of disposable status.
200, {"format":true,"disposable":false,"dns":true,"blocked":null}	Requested relay policy is inconclusive; use the unavailable-check policy.
200, {"format":false}	Invalid format; absent fields are not interpreted as a safe result.
200, {"format":true,"disposable":true,"dns":true,"whitelist":true}	Still disposable.
200, {"format":true,"disposable":false,"dns":false,"signals":["dns_indeterminate"]}	DNS remains inconclusive.
200, {"format":true,"disposable":false,"dns":false}	DNS policy applies.
429, {"error":"Rate limit exceeded","retry_after":60}	Retry policy applies; never classify the address as safe.
429, {"error":"Quota exceeded","reset_at":"2030-01-01T00:00:00Z"}	Wait for quota reset or operator action; no rapid retry loop.
503, {"error":"Service temporarily unavailable","retry_after":60}	Unavailable policy applies.
401, {"error":"Invalid API key"}	Configuration error.
200 with missing decision fields or invalid JSON; network timeout	Unavailable policy applies.

Also test + encoding and server-only keys. If implementing bulk validation, cover queued jobs and plain-text completion.

Documentation for agents

• Documentation index — links to the Markdown guides and references.
• OpenAPI specification — authentication, request parameters, response shapes, and errors for the core validation routes.
• This guide as Markdown — directly fetchable without navigating the site.
• Integration prompt as text — the same prompt shown above.

Every guide and reference page offers Copy as Markdown and View Markdown. Share only the pages relevant to your integration.