post https://verify.cmercury.com/api/file/
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 Address
- EmailAddress
- Email_Address
- 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