POSTNIX JSON REST API



Authentication

The Postnix API uses a single query string with your API Key. You can find this in the account dashboard when you sign in. This should be appended to the query string in any API request:

?api_key=<api_key>

Ping API

Use the ping API to ensure auth is working properly without using any credits or incuring any charges.

Example
HTTP GET
curl "http://api.postnix.com/ping?api_key=<api_key>"
Response

If all is well, you should receive a "pong" JSON response with a 200 OK status:

{
  "success": true,
  "ping": "pong"
}

Email Verification API

The email verification API is used to verify that an email address is deliverable. It can also be used to detect disposable email addresses.

Parameters
api_keyValid API key for your account
emailURL-encoded email to check for deliverability
Example
HTTP GET
curl "http://api.postnix.com/email/check?api_key=<api_key>&email=vance%40vancelucas.com"
Response
{
  "success": true,
  "email": "[email protected]",
  "valid": true,
  "status_type": "valid",
  "status_code": 250,
  "status_human": "Email is valid and deliverable",
  "provider": "google"
}

You will typically want to look at both the valid and status_type keys to determine if you want to allow the email or not.

Possible Status Types
validEmail is valid and deliverable - it should be okay to accept.
invalidEmail is not valid - mail server has confirmed that the mailbox does not exist, and you should not accept it. Mails sent to the mailbox will hard bounce.
invalid_emailEmail is not correctly formatted (i.e. not an email)
invalid_domainEmail domain is invalid (test.com, example.com, etc.)
accept_allEmail provider accepts all incoming email, and does not reveal if mailbox actually exists until mail is sent. You should go ahead and accept it, but you may get a hard bounce when sending.
impersonalEmail is valid, but is a generic account, like "sales", "info", "webmaster", etc. These accounts typically have lower open and clickthrough rates.
disposableEmail is a temporary or disposable email account, and should probably not be accepted. Disposable email accounts have much lower open and click rates, and are generally not worth having on your mailing list.
errorAn error has occured when attempting to check the email. Most of the time, this means the domain doesn't exist, or has no MX records. This status is also returned after a 2-second timeout is hit with no response from the mail server.

The Postnix API will always return a 200 OK status for email checks - even emails with an invalid or error status. In the event that the Postnix API returns a 4xx or 5xx status code, you should default to accepting the email address so that users are never prevented from signing up due to an issue with Postnix (500 error), or a lack of email credits for your account (402 error).


Batch Email Verification API

Exactly the same as the single email verification API, but can be used to verify up to 50 emails at a time. Use this option if you have a lot of emails to check to reduce the number of HTTP requests made to our API and get your results faster. Note that each email sent will use an email check credit - so if you send 50 emails, 50 credits will be used.

Parameters
api_keyValid API key for your account
bodyThe request body hould be a JSON object that with an "emails" key containing an array of emails to check
Example
HTTP POST
curl -H "Content-Type: application/json" -X POST -d '{"emails":["[email protected]","[email protected]"]}' "http://api.postnix.com/email/batch?api_key=<api_key>"
Response
{
    "success": true,
    "emails": {
        "[email protected]": {
            "success": false,
            "email": "[email protected]",
            "valid": false,
            "status_code": 0,
            "status_type": "error",
            "status_human": "connection timeout"
        },
        "[email protected]": {
            "success": true,
            "email": "[email protected]",
            "valid": false,
            "status_type": "invalid",
            "status_code": 550,
            "status_human": null,
            "provider": "google"
        }
    }
}