Bulk Email Verification

This API is for verifying a list of email addresses in a CSV file.

The report will be forwarded to the email address provided in the API request body.

An API token should be available in the account for using this API. An API token can be created from the Account Settings page of the cmercury application. You should include the token as X-Token in the header.

📘

Credits

The verification will use credits as many as the total contacts in the file. Hence, enough credits should be pre-existing in the account. You can add more credits as needed by contacting [email protected] or [email protected].

It is also possible to check the Abuse Reporter Score of each email address included in the file. A complete list of checks performed on each email address is available here.

Request Examples

Header

Accept: application/json
Content-Type: application/json
X-Token: <API-TOKEN>

Request Body

{
   "EmailAddress":"[email protected]",
   "FileUrl":"https://domain.com/filename.csv",
   "isAbuseReporterScoreOpted":True
}

API Response - Successful

{
    "RequestStatus": true,
    "RequestMessage": "File received. Please check your email for report.",
    "RequestUniqueIdentifier": "010000000123254658759652314525",
    "RequestMessageCode":1000
}

API Response - Failed due to insufficient credits

{
    "RequestStatus": false,
    "RequestMessage": "Insufficient Credit Balance for  verification.",
    "RequestUniqueIdentifier": "none",
  	"RequestMessageCode":1019
}

API Response - Failed as the file was not accessible from the URL

{
    "RequestStatus": false,
    "RequestMessage": "File is not accessible.",
    "RequestUniqueIdentifier": "none",
    "RequestMessageCode":1010
}

A complete list of status messages and their explanations are given in a separate table below.

Explanation of API Responses

Response Parameters

ParameterExplanation
RequestStatustrue The request was successful and the verification is in progress.

false The request failed due to the reason specified in the RequestMessage parameter.
RequestMessageThis parameter explains the status of the request. All status messages and their explanations are given below in a separate area.
RequestUniqueIdentifierThis is a unique identifier for identifying each request. It will be returned only when the request was successful. This can be used to retrieve reports later using reports API.
RequestMessageCodeA code to identify the message and programmatically handle it by the client application.

Details of status messages

RequestMessageExplanationRequestMessageCode
File received. Please check your email for report.The request has been accepted for verification and the report will be sent to the email address on completion.1000
Token is missingThe API token was not included as X-Token. Please ensure to have the X-Token field in the request header and include your API token as its value.1001
Token is invalidThe API Token provided in the X-Token field of the header is not valid. The token can be marked as invalid due to the following reasons

- Inactive cmercury account
- Inactive user account
- Error in Token
- Deleted Token

Please create a new API token and use that for making API requests.
1002
The account is inactive.The cmercury account is inactive. Kindly contact [email protected] for enabling and using your account.1003
User Account is inactive.The user account who is the owner of the API token is disabled in the cmercury account.1004
Verify feature is not enabled in this account.The Verify (List Cleaner) feature in the cmercury account is disabled. Please contact [email protected] to receive support.1005
Your credit balance is zero.The credit for verification in your cmercury account is zero. Please contact [email protected] to receive support in adding more credits.1006
Email Address is mandatory.The EmailAddress parameter in the request body is mandatory. This error shows that the parameter was empty or not included in the request body.1007
File URL is mandatoryThe FileUrl parameter in the request body is mandatory. This error shows that the parameter was empty or not included in the request body.1008
Only CSV files are supportedThe FileUrl parameter in the request body should only include links to a CSV file.1009
The File is not accessibleThe file mentioned in the FileUrl parameter is not accessible by the API. Please ensure that the file is existing at the path and can be accessed by the API.1010
The File is emptyThe file received by the API is empty.1011
The maximum allowed file size is 100MBThe size of the file was more than 100MB. Please submit a file which is 100MB or lower.1012
File contains reserved column headers.A few words can not be used as column names in the file as they are reserved by cmercury. You may remove other columns and send a file having the email column alone.

If all columns are mandatory for you, please contact [email protected] to identify the objectionable column name.
1013
Please include an allowed column header in fileThe file should have the email addresses under any of the allowed column names from a pre-defined list. The API will look for email addresses in those columns only. If none of the column names in the file matches the allowed headers, this error will be sent back.

The list of predefined column headers is listed below in a separate area.
1014
Duplicate occurance of allowed header is not permitted.This error is sent back when the system finds that more than one column is having the same name (duplication). Please remove the additional column or rename it.1015
Include only one header from the allowed column headersThe API does not allow having more than one column name from the predefined list. If there are two columns one named as email and another as emailaddress, this error is generated. Remove or rename the additional column.1016
The file could not be savedThis error is generated when the API could not save the file mostly due to system errors.1017
No rows found for verificationThis error is returned when API could not find any valid rows in the file.1018
Insufficient Credit Balance for verificationThe credit balance in the account is less than the number of contacts in the file. Contact [email protected] for adding sufficient credits to your account.1019
A file with the same name is already being verifiedIf the system finds that a verification of a file having the same name as the currently uploaded file is under progress, this error will be generated.

This is basically useful to prevent duplicate submission and unnecessary wastage of credits from the account.
1020
Some Error found. Please try again.The system has met a server error. The technical team will have a look into it. You can wait and try again later.2001
Internal Error. Please try again after some timeThe system has met a server error. The technical team will have a look into it. You can wait and try again later.2002
Error in submitting the fileThe system has met a server error. The technical team will have a look into it. You can wait and try again later.2003

Predefined Column Names

Please include your email address under the column name from any one of the following. Also note that having duplicate names, or having more than one from the below list will not be accepted by the API.

👍

Allowed names for email address column

  • Email
  • Email Address
  • EmailAddress
  • Email_Address
  • Mail
  • Mailid
  • Emailid
  • Mail_id
  • Email_id

Sample File

Use the following examples for creating CSV files.

EmailAddress
[email protected]
email22domain.tld
[email protected]
EmailAddress,Phone,FirstName,LastName
[email protected],1234567891,MyfName1,MyLname1
email22domain.tld,1234567892,MyfName2,MyLname2
[email protected],1234567893,MyfName3,MyLname3

Download Sample Files

Download Single Column Sample CSV File

Download Multiple Column Sample CSV File


Language
Click Try It! to start a request and see the response here!