How to manage EDG configuration?

Overview

This guide will walk you through the process of creating, reading, updating, and deleting your personalized configuration, which you can later use in the Email Domain Guard API to verify and analyze email addresses. The Email Domain Guard is a comprehensive email verification and domain analysis service designed to enhance communication integrity, data accuracy, and security for businesses. Customization of the configuration for Email Domain Guard allows clients to enable or disable specific checkers and adjust the weights for risks and trusts. This way, clients can tailor the settings to better meet their precise needs.

Learning Goals

In this instruction, you will focuse on:

How to create a configuration template,
How to read a configuration template,
How to update a configuration template,
How to delete a configuration template,
How to read all configurations,
How to read a specific version of a configuration template,
How to verify an email address using a configuration template,

Prerequisites

Authorization

Before trying CDQ APIs, user must be authenticated:

Paste the API Key in the console's security bar into the X-API-KEY field.

After pasting the API Key, the green padlock will appear.

Be careful

Green padlock doesn't mean that the API Key was pasted correctly.

Check your API key for missing characters or extra space before trying.

No API Key?

Check how to get one on authentication page.
Follow the steps above.

Documentation

In the following sections you will find out how to create, read, update and delete your configuration. Check the Email Analysis API Documentation for more details.

info

By using the interactive consol you can test the API directly in this instruction. If you don't have an APIKEY yet, you can see the example responses without sending the request. Expand the example response section added under every interactive console.

Create configuration

To create a new configuration with the configuration template follow the below steps:

Use the Create Configuration endpoint,
Sellect the Create a new configuration example,

Click Send button to execute the request,

Check the example response without sending the request.

Click to expand the response

Copy

Copied

{
	"name": "My configuration",
	"configuration": {
		"disposableMailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"disposableFactorWeight": 100
		},
		"dnsblChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"dnsblFactorWeight": 50
		},
		"freemailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"freemailFactorWeight": 40
		},
		"roleCategoryChecker": {
			"isEnabled": true
		},
		"whoisChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"newBornDomainFactorWeight": 85,
			"youngDomainFactorWeight": 10,
			"oldDomainFactorWeight": 10,
			"notPublicFactorWeight": 65,
			"youngDomainAgeThreshold": 365,
			"oldDomainAgeThreshold": 1095
		},
		"sharedEmailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"sharedEmailAddressFactorWeight": 50
		},
		"dataBreachChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"recentDataBreachFactorWeight": 20,
			"youngDataBreachFactorWeight": 10,
			"oldDataBreachFactorWeight": 5,
			"breachWithPasswordFactorWeight": 20,
			"breachWithMalwareFactorWeight": 20,
			"inflationaryBreachesFactorWeight": 10,
			"breachedDomainFactorWeight": 5,
			"youngDataBreachAgeThreshold": 365,
			"oldDataBreachAgeThreshold": 1095,
			"inflationaryBreachesCountThreshold": 25
		},
		"fraudCaseChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": false
		}
	},
	"version": 1,
	"id": "67e55a52826f904dcbf63743",
	"createdAt": "2025-03-27T14:01:54.259837898Z",
	"createdBy": "b3e96bd8-96a6-48f5-b378-610d177be354",
	"defaultConfiguration": false,
	"relatedConfigurations": []
}

Check the configuration ID.

Example configuration ID:

Copy

Copied

{
  "id": "67ff782fb523b0217598a324"
}

attention

Use the configuration ID in the next operations to read, update, and delete the configuration.

Configuration template structure

To understand the configuration template structure, here is a brief overview of the parameters:

Checker	Checker Name	Description
`dnsblChecker`	Disposable Mail Checker	Identifies email addresses associated with disposable or temporary email services, helping to maintain data quality and authenticity by filtering out unreliable addresses.
`dnsblChecker`	DNS Blacklist Checker	Checks if a domain's IP addresses are listed on DNS-based Blackhole Lists (DNSBLs) to identify potential sources of spam or malicious activity.
`freemailChecker`	Freemail Checker	Detects freemail addresses provided by public email service providers, assessing the quality and legitimacy of user-provided email addresses.
`roleCategoryChecker`	Role Category Checker	Identifies and categorizes role-based email addresses (e.g., support@example.com) to enhance personalization and communication strategies.
`whoisChecker`	Whois Checker	Retrieves and analyzes WHOIS information for a given domain, providing valuable details such as registration and expiration dates, and other relevant metadata.
`sharedEmailChecker`	Shared Email Checker	Identifies shared email addresses among community members while ensuring privacy through anonymous data sharing and secure hashing.
`dataBreachChecker`	Data Breach Checker	Analyzes email accounts and domains for potential data breaches using the "Have I Been Pwned" API, providing insights into the security status of the email address or domain.
`fraudCaseChecker`	Fraud Case Checker	Identifies email addresses involved in any reported and confirmed fraud cases via CDQ's Fraud Guard.

Configuration parameters

The configuration template contains several parameters that can be customized to suit your needs. Here are the key parameters you can set:

Parameter	Description
`"isEnabled": true`	If true, this checker will be enabled and used in your configuration.
`"isRiskCalculationEnabled": true`	If true, this checker will be used to calculate Risk Score.
`"disposableFactorWeight": 100`	Set a Factor Weight for this checker. 100 is the maximum Overall Risk Score.
`"youngDomainAgeThreshold": 365`	Defines the threshold for considering a domain as young. Default is 365 days.

Read configuration

To read an existing configuration follow the below steps:

Use the Read Configuration endpoint,
Use the configuration ID you received in the Create Configuration endpoint,

Click Send button to execute the request.

Check the example response without sending the request.

Click to expand the response

Copy

Copied

{
	"name": "My configuration",
	"configuration": {
		"disposableMailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"disposableFactorWeight": 100
		},
		"dnsblChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"dnsblFactorWeight": 50
		},
		"freemailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"freemailFactorWeight": 40
		},
		"roleCategoryChecker": {
			"isEnabled": true
		},
		"whoisChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"newBornDomainFactorWeight": 85,
			"youngDomainFactorWeight": 10,
			"oldDomainFactorWeight": 10,
			"notPublicFactorWeight": 65,
			"youngDomainAgeThreshold": 365,
			"oldDomainAgeThreshold": 1095
		},
		"sharedEmailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"sharedEmailAddressFactorWeight": 50
		},
		"dataBreachChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"recentDataBreachFactorWeight": 20,
			"youngDataBreachFactorWeight": 10,
			"oldDataBreachFactorWeight": 5,
			"breachWithPasswordFactorWeight": 20,
			"breachWithMalwareFactorWeight": 20,
			"inflationaryBreachesFactorWeight": 10,
			"breachedDomainFactorWeight": 5,
			"youngDataBreachAgeThreshold": 365,
			"oldDataBreachAgeThreshold": 1095,
			"inflationaryBreachesCountThreshold": 25
		},
		"fraudCaseChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": false
		}
	},
	"version": 1,
	"id": "67e55a52826f904dcbf63743",
	"createdAt": "2025-03-27T14:01:54.259Z",
	"createdBy": "b3e96bd8-96a6-48f5-b378-610d177be354",
	"defaultConfiguration": false,
	"relatedConfigurations": []
}

List Configurations

To read all configurations follow the below steps:

Use the List Configurations endpoint,
Set the startAfter to 0,

Click Send button to execute the request.

Check the example response without sending the request.

Click to expand the response

Copy

Copied

{
	"startAfter": "0",
	"nextStartAfter": "1",
	"total": 2,
	"values": [
		{
			"name": "My configuration",
			"id": "67e55a52826f904dcbf63743",
			"createdAt": "2025-03-27T14:01:54.259Z",
			"createdBy": "b3e96bd8-96a6-48f5-b378-610d177be354"
		},
		{
			"name": "Default configuration with risk score enabling",
			"id": "67c6b5e4e165a754e5098cad",
			"createdAt": "2025-03-04T08:12:20.021Z",
			"modifiedAt": "2025-03-04T08:12:20.021Z",
			"createdBy": "b3e96bd8-96a6-48f5-b378-610d177be354"
		}
	]
}

Update configuration

To update a configuration follow the below steps:

Use the Update Configuration endpoint,
Set the configurationId you want to update,
Modify the existing configuration,

Click Send button to execute the request.

Check the example response without sending the request.

Click to expand the response

Copy

Copied

{
	"name": "My configuration",
	"configuration": {
		"disposableMailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"disposableFactorWeight": 100
		},
		"dnsblChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"dnsblFactorWeight": 50
		},
		"freemailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"freemailFactorWeight": 40
		},
		"roleCategoryChecker": {
			"isEnabled": true
		},
		"whoisChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"newBornDomainFactorWeight": 85,
			"youngDomainFactorWeight": 10,
			"oldDomainFactorWeight": 10,
			"notPublicFactorWeight": 65,
			"youngDomainAgeThreshold": 365,
			"oldDomainAgeThreshold": 1095
		},
		"sharedEmailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"sharedEmailAddressFactorWeight": 50
		},
		"dataBreachChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"recentDataBreachFactorWeight": 20,
			"youngDataBreachFactorWeight": 10,
			"oldDataBreachFactorWeight": 5,
			"breachWithPasswordFactorWeight": 20,
			"breachWithMalwareFactorWeight": 20,
			"inflationaryBreachesFactorWeight": 10,
			"breachedDomainFactorWeight": 5,
			"youngDataBreachAgeThreshold": 365,
			"oldDataBreachAgeThreshold": 1095,
			"inflationaryBreachesCountThreshold": 25
		},
		"fraudCaseChecker": {
			"isEnabled": false,
			"isRiskCalculationEnabled": false
		}
	},
	"version": 2,
	"id": "67e55a52826f904dcbf63743",
	"createdAt": "2025-03-27T14:01:54.259Z",
	"modifiedAt": "2025-03-27T14:24:05.998010503Z",
	"createdBy": "b3e96bd8-96a6-48f5-b378-610d177be354",
	"defaultConfiguration": false,
	"relatedConfigurations": []
}

Delete configuration

To delete a configuration, follow the below steps:

Use the Delete Configuration endpoint,
Set the configurationId you want to delete,

Click Send button to execute the request.

Check the example response without sending the request.

Click to expand the response

Copy

Copied

{
	"name": "My configuration",
	"configuration": {
		"disposableMailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"disposableFactorWeight": 100
		},
		"dnsblChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"dnsblFactorWeight": 50
		},
		"freemailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"freemailFactorWeight": 40
		},
		"roleCategoryChecker": {
			"isEnabled": true
		},
		"whoisChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"newBornDomainFactorWeight": 85,
			"youngDomainFactorWeight": 10,
			"oldDomainFactorWeight": 10,
			"notPublicFactorWeight": 65,
			"youngDomainAgeThreshold": 365,
			"oldDomainAgeThreshold": 1095
		},
		"sharedEmailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"sharedEmailAddressFactorWeight": 50
		},
		"dataBreachChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"recentDataBreachFactorWeight": 20,
			"youngDataBreachFactorWeight": 10,
			"oldDataBreachFactorWeight": 5,
			"breachWithPasswordFactorWeight": 20,
			"breachWithMalwareFactorWeight": 20,
			"inflationaryBreachesFactorWeight": 10,
			"breachedDomainFactorWeight": 5,
			"youngDataBreachAgeThreshold": 365,
			"oldDataBreachAgeThreshold": 1095,
			"inflationaryBreachesCountThreshold": 25
		},
		"fraudCaseChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true
		}
	},
	"version": 4,
	"id": "67e55a52826f904dcbf63743",
	"createdAt": "2025-03-27T14:01:54.259Z",
	"modifiedAt": "2025-03-27T14:29:20.097Z",
	"createdBy": "b3e96bd8-96a6-48f5-b378-610d177be354",
	"defaultConfiguration": false,
	"relatedConfigurations": []
}

Read email verification configuration version

To read a specific version of an email verification configuration by id and version number follow the below steps:

Use the Read Email Verification Configuration Version endpoint,
Set the configurationId and version you want to read,

Click Send button to execute the request.

Check the example response without sending the request.

Click to expand the response

Copy

Copied

{
	"id": "67ea96a80ab6e12699b0bec0",
	"name": "My configuration1",
	"configurationId": "67ea96a80ab6e12699b0bebf",
	"version": 1,
	"configuration": {
		"disposableMailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"disposableFactorWeight": 100
		},
		"dnsblChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"dnsblFactorWeight": 50
		},
		"freemailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"freemailFactorWeight": 40
		},
		"roleCategoryChecker": {
			"isEnabled": true
		},
		"whoisChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"newBornDomainFactorWeight": 85,
			"youngDomainFactorWeight": 10,
			"oldDomainFactorWeight": 10,
			"notPublicFactorWeight": 65,
			"youngDomainAgeThreshold": 365,
			"oldDomainAgeThreshold": 1095
		},
		"sharedEmailChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"sharedEmailAddressFactorWeight": 50
		},
		"dataBreachChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true,
			"recentDataBreachFactorWeight": 20,
			"youngDataBreachFactorWeight": 10,
			"oldDataBreachFactorWeight": 5,
			"breachWithPasswordFactorWeight": 20,
			"breachWithMalwareFactorWeight": 20,
			"inflationaryBreachesFactorWeight": 10,
			"breachedDomainFactorWeight": 5,
			"youngDataBreachAgeThreshold": 365,
			"oldDataBreachAgeThreshold": 1095,
			"inflationaryBreachesCountThreshold": 25
		},
		"fraudCaseChecker": {
			"isEnabled": true,
			"isRiskCalculationEnabled": true
		}
	},
	"createdAt": "2025-03-31T13:20:40.677Z",
	"createdBy": "b3e96bd8-96a6-48f5-b378-610d177be354",
	"modifiedAt": "2025-03-31T13:20:40.677Z",
	"modifiedBy": "b3e96bd8-96a6-48f5-b378-610d177be354",
	"defaultConfiguration": false
}

Verify email address using configuration

To verify email address follow the below steps:

Use the Verify Email Address endpoint,
Sellect the Verify the Dev-Portal mail with configuration example,

Click Send button to execute the request.

Check the example response without sending the request.

Click to expand the response

Copy

Copied

{
	"email": "developer-portal@cdq.com",
	"summary": {
		"isBreachedDomain": false,
		"isBreachedEmail": false,
		"isBlacklisted": false,
		"isPublicWhois": true,
		"isSharedEmail": false,
		"isValidFormat": true,
		"isFreemail": false,
		"isRoleBased": false
	},
	"status": {
		"code": 200,
		"technicalKey": "OK",
		"details": [
			{
				"id": 200000000,
				"message": "Successful request.",
				"technicalKey": "DEFAULT_OK",
				"jsonRecord": {}
			},
			{
				"id": 200600005,
				"message": "Domain age is older than 1095 days.",
				"technicalKey": "EMAIL_DOMAIN_OLDER_THAN",
				"jsonRecord": {}
			}
		]
	},
	"risk": {
		"score": 0,
		"classification": {
			"name": "Very low risk",
			"technicalKey": "VERY_LOW_RISK"
		}
	},
	"format": {
		"isValidFormat": true,
		"parts": {
			"localPart": "developer-portal",
			"topLevelDomain": "com",
			"baseDomain": "cdq",
			"domain": "cdq.com"
		}
	},
	"domain": {
		"isValidDomain": true
	},
	"sharing": {
		"isSharedEmail": false,
		"subscribers": 0
	},
	"role": {
		"isRoleBased": false
	},
	"freemail": {
		"isFreemail": false
	},
	"disposable": {},
	"whois": {
		"isPublicWhois": true,
		"entry": {
			"dates": {
				"creationDate": "1996-12-14T05:00:00",
				"updatedDate": "2024-11-08T23:48:45",
				"ageInDays": 10334,
				"ageInYears": 28.312328767123287
			},
			"registrar": {
				"name": "Amazon Registrar, Inc.",
				"email": "trustandsafety@support.aws.com"
			}
		}
	},
	"dnsBlacklist": {
		"isDnsBlacklisted": false,
		"dnsBlacklists": []
	},
	"breaches": {
		"isBreachedEmail": false,
		"isBreachedDomain": false
	},
	"fraudCases": {}
}

Conclusion

In this guide, you learned how to create, read, update, and delete your personalized configuration for the Email Domain Guard API.