Cookie consent

We use some essential cookies to make this website work. We'd like to set additional cookies to help us measure your experience when you view and interact with the website.

Cookie policy


This endpoint validates an email address in real-time to check whether it's capable of receiving email. It performs checks on the syntax of the email address, the associated MX record and the individual mailbox. It identifies disposable email addresses (DEAs) and provides alternative suggestions if typos are detected.

Email validation: Enable access on your API key using the Features page or by contacting us.

Request URL


Path parameters

apikeyYour API keyPCW45-12345-12345-1234X
emailThe URL-encoded email address you wish to

Querystring parameters

formatSets the format of the response, xml or json (default unless "application/xml" header is detected)format=json
identifierSpecifies your own meaningful identifier for the request such as "websiteA" or "client123"; you can view usage for each identifier on the Identifier Usage page, which may be helpful when using your API key across multiple websites, apps or clientsidentifier=websiteA
timeoutSets the maximum time in milliseconds to wait for the request to complete; the timeout should be an integer between 1000 and 120000, the default is 10000timeout=2000

Example request and response


	"warning": "This is a test key do NOT use it live (always returns true)",
	"state": "Test Key",
	"valid": true,
	"score": "100",
	"processtime": "0"

Response fields

warningAn advisory message about the validation processOnly reduced validation is available for this domain
stateOne of the following states, which may change from time to time:

  • Mailbox Does Not Exist
  • Mailbox Temporarily Unavailable
  • Mailbox Validation Timeout
  • Smtp Connection Timeout
  • Success (Server is Catch All)
  • Success
  • Domain is Well Known DEA
  • Domain Does Not Exist
  • Test Key
Test Key
validA true or false indicating whether the email address is validtrue
scoreA validation score between 0 to 100 where higher is better100
processtimeThe time spent processing the validation, measured in ms321
alternativeA did-you-mean-style alternative spelling where

Integration advice

  • URL encode all special characters (including /) in your request parameters with %xx encoding
  • Verify your request was successful by checking for an HTTP status code of 200; see all HTTP status codes with descriptions
  • When using your API key across multiple websites, apps or clients, set the identifier querystring parameter to a meaningful value such as "websiteA" or "client123"; you'll then be able to view these identifiers and the number of requests made by each one on the Identifier Usage page
  • Requests will usually return within a second but may take longer depending on the email address provider; use the timeout querystring parameter to set a maximum time to wait
  • Treat all response fields as optional

Credit cost

Each request costs 1.2 credits.

Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.