# Verify Email Address

The Email Domain Guard consists of multiple checkers and a risk scoring feature. Each of the checkers analyzes a specific aspect of the given email address, the assessment via the checkers is then combined in terms of a multifactor analysis to a risk score.
Available checkers:
  - Email Component Extractor: Accurately separates an email address into its local part and domain, and then attempt to derive the base domain from it.
  - Email Format Checker: Validates the structure and syntax of email addresses to ensure they follow standard conventions.
  - Domain Existence Checker: Verifies the existence and accessibility of domain names, ensuring communications are directed to functional domains.
  - Disposable Mail Checker: Detects disposable or temporary email addresses, ensuring the quality and authenticity of user-provided email addresses.
  - Freemail Checker: Identifies freemail addresses, helping to assess the quality and legitimacy of user-provided email addresses.
  - Role Category Checker: Identifies role-based email addresses, enhancing personalization and optimizing resource allocation.
  - Whois Checker: Retrieves and analyzes whois information for domains, providing valuable details such as registration date and domain age.
  - DNSBL Checker: Checks if email domain IP addresses are listed on DNS-based Blackhole Lists (DNSBLs), identifying potential sources of spam or malicious activity.
  - Data Breach Checker: Analyzes email accounts and domains for potential data breaches using the “Have I Been Pwned” API.
  - Shared Email Checker: Identifies shared email addresses among community members while ensuring privacy through anonymous data sharing and secure hashing.
  - Fraud Case Checker: Identifies email addresses involved in any reported and confirmed fraud cases via CDQ's Fraud Guard.

Endpoint: POST /emails/verify
Version: 1
Security: apiKey

## Request fields (application/json):

  - `email` (string, required)
    An email address as defined by IETF.
    Example: "john.doe@gmail.com"

  - `configurationId` (string)
    Uniquely identifies a configuration.
    Example: "c074b9f3-abf0-4f8e-9a20-74deb6cfa2a4"

## Response 200 fields (application/json):

  - `email` (string)
    An email address as defined by IETF.
    Example: "john.doe@gmail.com"

  - `summary` (object)
    Summary of the email verification result.yaml.

  - `summary.isBreachedDomain` (boolean)
    Indicates whether the domain has been found in data breaches.

  - `summary.isBreachedEmail` (boolean)
    Indicates whether the email address has been found in data breaches.

  - `summary.isDisposable` (boolean)
    Indicates whether the email address is disposable or temporary.

  - `summary.isBlacklisted` (boolean)
    Indicates whether the domain's IP addresses are listed on any Domain Name System blacklist

  - `summary.isPublicWhois` (boolean)
    Indicates whether the domain's WHOIS information is publicly available

  - `summary.isSharedEmail` (boolean)
    Indicates whether the email address is found in the shared email database of the CDQ Data Sharing Community.
    Example: true

  - `summary.isValidFormat` (boolean)
    Indicates whether the email address has a valid format.
    Example: true

  - `summary.isFreemail` (boolean)
    Indicates whether the email address is from a freemail provider (e.g. Gmail, Yahoo)

  - `summary.isRoleBased` (boolean)
    Indicates whether the email address is a role-based address (e.g. support@example.com).

  - `summary.isFraudCaseDetected` (boolean)
    Indicates whether the fraud case was detected for given email address.

  - `status` (object)
    Details about status or error of a service

  - `status.code` (integer, required)
    RFC 7231 status code for this error.
    Example: "200"

  - `status.technicalKey` (string, required)
    Technical key describing the status or error
    Example: "OK"

  - `status.details` (array, required)

  - `status.details.id` (integer, required)
    9-digit code which is uniquely identifying a message
    Example: 200000004

  - `status.details.message` (string, required)
    Human-readable message which may also be presented in user interface.
    Example: "The job came to an end and finished successfully."

  - `status.details.technicalKey` (string)
    Technical key to uniquely identify a message.
    Example: "JOB_FINISHED"

  - `status.details.jsonPath` (string)
    JSONPath as specified by the IETF standard
    Example: "$.businessPartner.names[0].value"

  - `status.details.jsonRecord` (string)
    Object provided in plain JSON format.
    Example: "{ \"key\" : \"value\"}"

  - `status.path` (string)
    Requested path which caused this error.
    Example: "/v2/businesspartners/lookup"

  - `status.timestamp` (string)
    ISO 8601 representation of the timestamp.
    Example: "2026-03-13T12:22:55Z"

  - `risk` (object)
    Details about the risk score and classification.

  - `risk.score` (integer)
    A numerical value (0-100) representing the risk score associated with the email address.
    Example: 100

  - `risk.classification` (object)
    The classification of the risk based on the risk score, indicating the level of risk such as "Very low risk", "Low risk", "Medium risk", "High risk", or "Very high risk".

  - `risk.classification.name` (string)
    The classification of the risk based on the risk score, indicating the level of risk such as "Very low risk", "Low risk", "Medium risk", "High risk", or "Very high risk".
    Example: "Very low risk"

  - `risk.classification.technicalKey` (string)
    The classification of the risk based on the risk score, indicating the level of risk such as "Very low risk", "Low risk", "Medium risk", "High risk", or "Very high risk".
    Enum: "VERY_LOW_RISK", "LOW_RISK", "MEDIUM_RISK", "HIGH_RISK", "VERY_HIGH_RISK"

  - `format` (object)
    Details about the email format.

  - `format.isValidFormat` (boolean)
    Indicates whether the email address has a valid format.
    Example: true

  - `format.parts` (object)
    Contains the different parts of an email address, including the local part, top-level domain, base domain, and full domain.

  - `format.parts.localPart` (string)
    The account name of the email address.
    Example: "john.doe"

  - `format.parts.topLevelDomain` (string)
    The top-level domain of the email address.
    Example: "com"

  - `format.parts.baseDomain` (string)
    The base domain of the email address.
    Example: "gmail"

  - `format.parts.domain` (string)
    The full domain of the email address.
    Example: "gmail.com"

  - `domain` (object)
    Details about the domain verification.

  - `domain.isValidDomain` (boolean)
    Indicates whether the domain of the email address is valid and operational.
    Example: true

  - `sharing` (object)
    Details about the shared email verification.

  - `sharing.isSharedEmail` (boolean)
    Indicates whether the email address is found in the shared email database of the CDQ Data Sharing Community.
    Example: true

  - `sharing.subscribers` (integer)
    The number of unique community members that use this email address for conversations with customers or suppliers.
    Example: 100

  - `role` (object)
    Details about the shared email verification.

  - `role.isRoleBased` (boolean)
    Indicates whether the email address is a role-based address (e.g. support@example.com).

  - `role.roleCategory` (object)
    The category of the role-based email address, if applicable.

  - `role.roleCategory.name` (string)
    The category name of the role-based email address, if applicable.
    Example: "Human Resources"

  - `role.roleCategory.technicalKey` (string)
    The category technical key of the role-based email address, if applicable.
    Enum: "GENERAL_INQUIRIES", "SALES_AND_MARKETING", "CUSTOMER_SUPPORT", "BILLING_AND_FINANCE", "HUMAN_RESOURCES", "TECHNICAL_SUPPORT", "ADMINISTRATION", "WEBSITE_AND_IT", "MEDIA_AND_PR", "FEEDBACK_AND_SUGGESTIONS", "SOCIAL_MEDIA_AND_COMMUNITY", "EVENTS_AND_PROMOTIONS", "RESEARCH_AND_DEVELOPMENT", "SECURITY_AND_PRIVACY", "NEWSLETTER_SUBSCRIPTIONS"

  - `freemail` (object)
    Details about the freemail verification.

  - `freemail.isFreemail` (boolean)
    Indicates whether the email address is from a freemail provider (e.g. Gmail, Yahoo)

  - `freemail.provider` (object)
    Information about the email provider, if applicable

  - `freemail.provider.name` (string)
    The name of the freemail/disposable email/dnsbl provider.
    Example: "Gmail"

  - `freemail.provider.website` (object)
    Website related to the email provider, if applicable

  - `freemail.provider.website.url` (string)
    The actual company website URL.
    Example: "https://meta.cdq.com/Public:CDQ_data_model"

  - `disposable` (object)
    Details about the disposable email verification.

  - `disposable.isDisposable` (boolean)
    Indicates whether the email address is disposable or temporary.

  - `disposable.provider` (object)
    Information about the email provider, if applicable

  - `disposable.provider.name` (string)
    The name of the freemail/disposable email/dnsbl provider.
    Example: "Gmail"

  - `disposable.provider.website` (object)
    Website related to the email provider, if applicable

  - `disposable.provider.website.url` (string)
    The actual company website URL.
    Example: "https://meta.cdq.com/Public:CDQ_data_model"

  - `whois` (object)
    Details about the WHOIS verification.

  - `whois.isPublicWhois` (boolean)
    Indicates whether the domain's WHOIS information is publicly available

  - `whois.entry` (object)
    Information about the domain's WHOIS data, including creation date, age, registrar, and registrant details

  - `whois.entry.dates` (object)
    Dates related to the WHOIS information.

  - `whois.entry.dates.creationDate` (string)
    The creation date of the domain.
    Example: "2026-03-13T12:22:55Z"

  - `whois.entry.dates.updatedDate` (string)
    The updated date of the domain.
    Example: "2026-03-13T12:22:55Z"

  - `whois.entry.dates.ageInDays` (integer)
    The age of the domain in days.
    Example: 2

  - `whois.entry.dates.ageInYears` (number)
    The age of the domain in years

  - `whois.entry.registrar` (object)
    Information about the contact of a domain

  - `whois.entry.registrar.name` (string)
    The name of the registrant.
    Example: "John Doe"

  - `whois.entry.registrar.organization` (string)
    The name of the WhoIs contact.
    Example: "Amazon Register, Inc."

  - `whois.entry.registrar.street` (string)
    The address of the WhoIs contact.
    Example: "Musterstrasse 1"

  - `whois.entry.registrar.city` (string)
    The city of the WhoIs contact.
    Example: "Zurich"

  - `whois.entry.registrar.state` (string)
    The state of the WhoIs contact.
    Example: "ZH"

  - `whois.entry.registrar.postalCode` (string)
    The postal code of the WhoIs contact.
    Example: "8000"

  - `whois.entry.registrar.country` (string)
    Country name.
    Example: "Switzerland"

  - `whois.entry.registrar.email` (string)
    The contact email of the domain.
    Example: "noreply@registrar.amazon.com"

  - `whois.entry.registrant` (object)
    Information about the contact of a domain

  - `whois.entry.registrant.name` (string)
    The name of the registrant.
    Example: "John Doe"

  - `whois.entry.registrant.organization` (string)
    The name of the WhoIs contact.
    Example: "Amazon Register, Inc."

  - `whois.entry.registrant.street` (string)
    The address of the WhoIs contact.
    Example: "Musterstrasse 1"

  - `whois.entry.registrant.city` (string)
    The city of the WhoIs contact.
    Example: "Zurich"

  - `whois.entry.registrant.state` (string)
    The state of the WhoIs contact.
    Example: "ZH"

  - `whois.entry.registrant.postalCode` (string)
    The postal code of the WhoIs contact.
    Example: "8000"

  - `whois.entry.registrant.country` (string)
    Country name.
    Example: "Switzerland"

  - `whois.entry.registrant.email` (string)
    The contact email of the domain.
    Example: "noreply@registrar.amazon.com"

  - `dnsBlacklist` (object)
    Details about the DNS blacklist verification.

  - `dnsBlacklist.isDnsBlacklisted` (boolean)
    Indicates whether the domain's IP addresses are listed on any Domain Name System blacklist

  - `dnsBlacklist.dnsBlacklists` (array)

  - `dnsBlacklist.dnsBlacklists.url` (string)
    The url of the Domain Name System blacklist
    Example: "zen.spamhaus.org"

  - `breaches` (object)
    Details about the data breaches the email address has been associated with.
The data originates from the website haveibeenpwned.com

  - `breaches.isBreachedEmail` (boolean)
    Indicates whether the email address has been found in data breaches.

  - `breaches.breachedEmailCount` (number)
    The total number of data breaches the email address/domain has been found in.

  - `breaches.emailBreaches` (array)
    Information about the specific data breaches the email address has been associated with, including breach name, date, description, and data class exposed.

  - `breaches.emailBreaches.name` (string)
    The name of the data breach.
    Example: "Adobe"

  - `breaches.emailBreaches.title` (string)
    The title of the data breach.
    Example: "Adobe breach"

  - `breaches.emailBreaches.domain` (string)
    The domain of the data breach.
    Example: "adobe.com"

  - `breaches.emailBreaches.breachDate` (string)
    The date of the data breach.
    Example: "2026-03-13T12:22:55Z"

  - `breaches.emailBreaches.pwnCount` (number)
    The number of accounts exposed in the data breach.
    Example: 153000000

  - `breaches.emailBreaches.description` (string)
    The description of the data breach.
    Example: "In October 2013, 153 million Adobe accounts were breached with each containing an internal ID, username, email, encrypted password and a password hint in plain text."

  - `breaches.emailBreaches.dataClasses` (array)
    The data classes exposed in the data breach.
    Example: ["Email addresses","Passwords"]

  - `breaches.emailBreaches.isVerified` (boolean)
    Indicates whether the data breach has been verified.
    Example: true

  - `breaches.emailBreaches.isFabricated` (boolean)
    Indicates whether the data breach has been fabricated.

  - `breaches.emailBreaches.isSensitive` (boolean)
    Indicates whether the data breach contains sensitive information.

  - `breaches.emailBreaches.isRetired` (boolean)
    Indicates whether the data breach has been retired.

  - `breaches.emailBreaches.isSpamList` (boolean)
    Indicates whether the data breach is a spam list.

  - `breaches.emailBreaches.isMalware` (boolean)
    Indicates whether the data breach contains malware.

  - `breaches.isBreachedDomain` (boolean)
    Indicates whether the domain has been found in data breaches.

  - `breaches.breachedDomainCount` (number)
    The total number of data breaches the domain has been found in.

  - `breaches.domainBreaches` (array)
    Information about the specific data breaches the domain has been associated with, including breach name, date, description, and data class exposed.

  - `breaches.domainBreaches.name` (string)
    The name of the data breach.
    Example: "Adobe"

  - `breaches.domainBreaches.title` (string)
    The title of the data breach.
    Example: "Adobe breach"

  - `breaches.domainBreaches.domain` (string)
    The domain of the data breach.
    Example: "adobe.com"

  - `breaches.domainBreaches.breachDate` (string)
    The date of the data breach.
    Example: "2026-03-13T12:22:55Z"

  - `breaches.domainBreaches.pwnCount` (number)
    The number of accounts exposed in the data breach.
    Example: 153000000

  - `breaches.domainBreaches.description` (string)
    The description of the data breach.
    Example: "In October 2013, 153 million Adobe accounts were breached with each containing an internal ID, username, email, encrypted password and a password hint in plain text."

  - `breaches.domainBreaches.dataClasses` (array)
    The data classes exposed in the data breach.
    Example: ["Email addresses","Passwords"]

  - `breaches.domainBreaches.isVerified` (boolean)
    Indicates whether the data breach has been verified.
    Example: true

  - `breaches.domainBreaches.isFabricated` (boolean)
    Indicates whether the data breach has been fabricated.

  - `breaches.domainBreaches.isSensitive` (boolean)
    Indicates whether the data breach contains sensitive information.

  - `breaches.domainBreaches.isRetired` (boolean)
    Indicates whether the data breach has been retired.

  - `breaches.domainBreaches.isSpamList` (boolean)
    Indicates whether the data breach is a spam list.

  - `breaches.domainBreaches.isMalware` (boolean)
    Indicates whether the data breach contains malware.

  - `fraudCases` (object)
    Details about the fraud case verification.

  - `fraudCases.isFraudCaseDetected` (boolean)
    Indicates whether the fraud case was detected for given email address.

  - `fraudCases.fraudCasesCount` (integer)
    The total number of fraud cases the email address has been found in.
    Example: 1

  - `fraudCases.fraudCases` (array)

  - `fraudCases.fraudCases.cdqId` (string)
    The unique identifier of the fraud case.
    Example: "ADhby5HQCN"

  - `fraudCases.fraudCases.dateOfAttack` (string)
    The date of the fraud case attack.
    Example: "2026-03-13T12:22:55Z"

  - `fraudCases.fraudCases.description` (string)
    The description of the fraud case.
    Example: "Company received information from fake email address."

  - `debugInfo` (object)
    Debug information about the email verification.

  - `debugInfo.checkerResults` (array)
    Example: ["a"]

## Response 400 fields (application/json):

  - `status` (object)
    Details about status or error of a service

  - `status.code` (integer, required)
    RFC 7231 status code for this error.
    Example: "200"

  - `status.technicalKey` (string, required)
    Technical key describing the status or error
    Example: "OK"

  - `status.details` (array, required)

  - `status.details.id` (integer, required)
    9-digit code which is uniquely identifying a message
    Example: 200000004

  - `status.details.message` (string, required)
    Human-readable message which may also be presented in user interface.
    Example: "The job came to an end and finished successfully."

  - `status.details.technicalKey` (string)
    Technical key to uniquely identify a message.
    Example: "JOB_FINISHED"

  - `status.details.jsonPath` (string)
    JSONPath as specified by the IETF standard
    Example: "$.businessPartner.names[0].value"

  - `status.details.jsonRecord` (string)
    Object provided in plain JSON format.
    Example: "{ \"key\" : \"value\"}"

  - `status.path` (string)
    Requested path which caused this error.
    Example: "/v2/businesspartners/lookup"

  - `status.timestamp` (string)
    ISO 8601 representation of the timestamp.
    Example: "2026-03-13T12:22:55Z"


## Response 401 fields

## Response 500 fields