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

Parameter

Explanation

RequestStatus

true The request was successful and the verification is in progress.

false The request failed due to the reason specified in the RequestMessage parameter.

RequestMessage

This parameter explains the status of the request. All status messages and their explanations are given below in a separate area.

RequestUniqueIdentifier

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

RequestMessageCode

A code to identify the message and programmatically handle it by the client application.

Details of status messages

RequestMessage

Explanation

RequestMessageCode

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 missing

The 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 invalid

The 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 mandatory

The 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 supported

The FileUrl parameter in the request body should only include links to a CSV file.

1009

The File is not accessible

The 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 empty

The file received by the API is empty.

1011

The maximum allowed file size is 100MB

The 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 file

The 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 headers

The 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 saved

This error is generated when the API could not save the file mostly due to system errors.

1017

No rows found for verification

This error is returned when API could not find any valid rows in the file.

1018

Insufficient Credit Balance for verification

The 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 verified

If 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 time

The 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 file

The 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!