# 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:
  - : Accurately separates an email address into its local part and domain, and then attempt to derive the base domain from it.
  - : Validates the structure and syntax of email addresses to ensure they follow standard conventions.
  - : Verifies the existence and accessibility of domain names, ensuring communications are directed to functional domains.
  - : Detects disposable or temporary email addresses, ensuring the quality and authenticity of user-provided email addresses.
  - : Identifies freemail addresses, helping to assess the quality and legitimacy of user-provided email addresses.
  - : Identifies role-based email addresses, enhancing personalization and optimizing resource allocation.
  - : Retrieves and analyzes whois information for domains, providing valuable details such as registration date and domain age.
  - : Checks if email domain IP addresses are listed on DNS-based Blackhole Lists (DNSBLs), identifying potential sources of spam or malicious activity.
  - : Analyzes email accounts and domains for potential data breaches using the “Have I Been Pwned” API.
  - : Identifies shared email addresses among community members while ensuring privacy through anonymous data sharing and secure hashing.
  - : 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: "400"

  - `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: "Business Partner Name is mandatory."

  - `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: "2025-09-01T14:16:48Z"

  - `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.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.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.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.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://cdq.com"

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

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

  - `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: "2025-09-01T14:16:48Z"

  - `whois.entry.dates.updatedDate` (string)
    The updated date of the domain.
    Example: "2025-09-01T14:16:48Z"

  - `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

  - `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.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: "2025-09-01T14:16:48Z"

  - `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.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.

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

  - `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: "2025-09-01T14:16:48Z"

  - `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: "400"

  - `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: "Business Partner Name is mandatory."

  - `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: "2025-09-01T14:16:48Z"