--- title: "Analyze an email address" method: GET path: "/email-intelligence/v1/process" tags: ["Email Intelligence"] --- # Analyze an email address `GET /email-intelligence/v1/process` ## Request - Base URL: `https://api.restcountries.com` - URL: `https://api.restcountries.com/email-intelligence/v1/process` - Auth: one of: - HTTP bearer - API key in query parameter `api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Runs one email address through the pipeline and returns a single record describing it: its parts (local, username, tag, domain), the top-level domain and the country that administers it, what's known about the domain (mail provider, category, live MX records, SPF and DMARC policy, registration dates), whether it has a Gravatar, a did_you_mean correction for likely typos, and boolean attributes such as is_free, is_disposable, is_forwarder, and is_likely_role_based. The address is read from email, or from q as an alias, and one of the two is required; a request naming neither is rejected with a 400 (email_intelligence.email_missing). A malformed address is not an error: it answers 200 with attributes.is_valid_syntax false and no lookups run. Every response carries the same shape, and a value the data can't name comes back null. Omitting a branch with response_fields_omit also skips the lookup behind it (for example gravatar or domain.registration), which makes the request faster. See https://restcountries.com/docs/email-intelligence for the full reference. ## Query parameters - `email` string - `q` string - `response_fields` string - `response_fields_omit` string - `pretty` boolean ## Response `200` Analysis record for the requested email address, always a single object. - EmailProcessResponse - `data` object, required - `objects` EmailRecord[], required - `email` string: The address the request resolved to: the email parameter, then the q alias. Echoed verbatim. - `did_you_mean` string, nullable: A corrected address when the domain looks like a typo of a well-known one (someone@gmial.com suggests someone@gmail.com); null otherwise, which is most of the time. Treat it as a prompt for your user, never an automatic correction. - `parts` object: The address split on its last @. The domain half is lowercased; the local half is preserved exactly as sent. - `local` string, nullable: Everything before the @, tag included. - `username` string, nullable: The local part with any plus-addressing tag removed: the mailbox the address delivers to. - `tag` string, nullable: Everything after the local part's first +, or null when there is no +. - `domain` string, nullable: Everything after the last @, lowercased. The value the MX lookup runs against. - `tld` object: The domain's top-level label and the country that administers it. This is provenance, not location: many ccTLDs (io, ai, tv, me, co) are used worldwide with no connection to the country. - `name` string, nullable: The DNS top-level label, lowercased (example.co.uk gives uk). - `country` object - `name` string, nullable: The country holding the ccTLD, from the same dataset the Countries API serves; null for generic or supranational suffixes such as com or eu. - `emoji` string, nullable: That country's flag emoji, or null alongside a null name. - `domain` object: What's known about the domain half of the address. - `provider` object: The operator handling mail for the domain, read from its MX records and never from the domain name. Every key is null when the operator isn't recognized, which includes every self-hosted mail server. - `name` string, nullable: Operator name (e.g. Google, Microsoft, Proton). - `type` 'mailbox' | 'gateway' | 'forwarding' | 'disposable' | 'null', nullable: mailbox runs the mailbox itself; gateway is a filtering layer in front of a mailbox host that DNS doesn't reveal; forwarding relays elsewhere; disposable hands out throwaway mailboxes. - `url` string, nullable: The operator's homepage. - `category` 'disposable' | 'forwarding' | 'free' | 'education' | 'government' | 'custom' | 'no_mail' | 'null', nullable: One mutually exclusive bucket, first match wins in the order listed. custom means the domain accepts mail and matched none of the others (a company or a personal vanity domain); no_mail means it publishes no way to receive mail. - `mx` object[]: The domain's mail exchangers, resolved live from DNS, lowest priority first with ties broken alphabetically. Empty when the domain publishes none, declares a null MX, doesn't resolve, or the lookup fails; those cases aren't distinguished. - `exchange` string: Mail exchanger hostname, lowercased, without the trailing root dot. - `priority` integer: The record's preference value. Lower is tried first. - `registration` object: Registration dates read over RDAP, as YYYY-MM-DD. A null means not available (no RDAP, redacted, or the lookup timed out), never recently registered. - `registered_on` string, date, nullable: Date the domain was first registered. - `updated_on` string, date, nullable: Date the registry record last changed. - `transferred_on` string, date, nullable: Date the domain last changed hands, where the registry publishes it. - `expires_on` string, date, nullable: Date the current registration lapses if not renewed. - `age_days` integer, nullable: Whole days since registered_on; null whenever registered_on is. - `authentication` object: What the domain publishes about who may send mail as it. A present of false means the domain publishes nothing or the lookup couldn't complete. DKIM is not reported, because selectors can't be discovered. - `spf` object - `present` boolean: Whether the domain publishes an SPF record. - `policy` 'strict' | 'softfail' | 'neutral' | 'allow_all' | 'null', nullable: What the record says to do with an unauthorized sender: strict (-all), softfail (~all), neutral (?all), or allow_all (+all). A redirect= is followed one hop. - `record` string, nullable: The raw SPF record. - `dmarc` object - `present` boolean: Whether the domain publishes a DMARC record. - `policy` 'none' | 'quarantine' | 'reject' | 'null', nullable: The record's p= tag. - `subdomain_policy` 'none' | 'quarantine' | 'reject' | 'null', nullable: The record's sp= tag; null when unset, in which case subdomains inherit policy. - `percentage` integer, nullable: The record's pct= tag: the share of mail the policy applies to. - `record` string, nullable: The raw DMARC record. - `gravatar` object: Whether the address has a Gravatar. The check sends a hash of the address to Gravatar; omit it with response_fields_omit=gravatar if that isn't acceptable. - `exists` boolean: Whether a Gravatar is registered for the address. A true is decent evidence the address is real and in use; a false means almost nothing. - `avatar_url` string, nullable: URL of the image, or null. - `profile_url` string, nullable: URL of the public Gravatar profile, or null. - `attributes` object: Boolean flags about the address. - `is_valid_syntax` boolean: Whether the address is shaped like an email address. Gates everything else. It does not mean deliverable. - `is_free` boolean: Whether the domain belongs to a free mailbox provider. Matched against the domain only, so a company on Google Workspace is not free. - `is_disposable` boolean: Whether the address is a throwaway, judged by the domain and then by its mail exchangers. Every disposable address is also free. - `is_forwarder` boolean: Whether the address relays to a mailbox elsewhere. A true is good evidence; a false is weak evidence. - `is_likely_role_based` boolean: Whether the local part names a function rather than a person (support@, billing@), matched exactly and case-insensitively against parts.username. - `has_plus_addressing` boolean: Whether the local part carries a + tag, i.e. whether parts.tag is non-null. Syntactic, not provider-aware. - `meta` ResultMeta - `total` integer, required: Number of objects returned. - `request_id` string, required - `duration` integer, required: Server-side processing time in milliseconds. ## Other responses - `400`: Bad request. Malformed parameters or unsupported property. - `401`: Unauthorized. Missing, invalid, expired, or revoked API key. - `403`: Forbidden. The account is deleted, disabled, frozen, or pending approval; the request origin isn't in the key's allowed CORS origins; a paid-only field was used as a search, filter, or lookup target on a plan that doesn't include it; a limit above the plan's ceiling but within the paid maximum was requested on a non-paid plan; or the monthly quota has been exceeded past the soft-limit grace period. - `404`: Not found. The route doesn't match any defined endpoint, the API isn't active, or listing isn't supported for this API version. - `405`: Method not allowed. Every endpoint is GET-only. - `410`: Gone. The requested API version is no longer active. - `429`: Too Many Requests. Sustained traffic above the edge rate limit (20 requests per 10 seconds) is rejected by Cloudflare before the request reaches the API, so this response is generated at the edge and does not carry the standard JSON error envelope. Back off briefly and retry. The IP API can also answer 429 itself when the upstream geolocation service is rate limiting lookups; that response does carry the standard JSON error envelope, with the code ip.lookup_rate_limited. ## Changes - **2026-11-12** `c3d3a3e5f440`: 1 info - endpoint added [Operation history](https://skmtc.dev/restcountries/apis/rest-countries/changes/email-intelligence/v1/process/get.md) --- [API](https://skmtc.dev/restcountries/apis/rest-countries.md) - [All operations](https://skmtc.dev/restcountries/apis/rest-countries/llms.txt) - [OpenAPI document](https://skmtc.dev/restcountries/apis/rest-countries/revisions/c3d3a3e5f440?raw)