Introduction

Welcome to the MailDB REST API documentation.

The MailDB API is a REST based implementation, accessible via standard HTTP requests using Basic Auth. All response are returned in JSON format.

Authentication

Before you can begin using the MailDB API, you must create an API key from within the member panel. Make sure you keep all of your API keys secret from public view, as they will provide full access to each service.

Authentication is performed via standard HTTP Basic Auth. Your API key should be set as the username portion, and the password portion can be left blank.

Example Request

curl "https://api.maildb.io/v1/search/domain?domain=maildb.io" \
  -u abcdef0123456789abcdef0123456789:

Errors

The standard HTTP response codes are used to signal the success or failure of a given request.

Response codes within the 2xx range indicate success.

Response codes within the 4xx range indicate an error, and the response body will contain a JSON formatted response detailing the error.

Response codes within the 5xx range indicate an error has occurred on our end.

Code
Detail
200
OK - Everything went as expected.
400
Bad Request - The request could not be processed, usually because of an invalid parameter.
401
Unauthorized - A valid API key was not provided.
404
Not Found - The given resource endpoint could not be found.
429
Too Many Requests - A rate limiting error, signaling you are sending too many API requests too quickly.
5xx
MailDB Server Error - Something wrong on our end, should be rare.

Example Error Response

{
  "errors": [
    {
      "id": "bad_request",
      "status": 400,
      "param": "domain",
      "detail": "Domain parameter is required"
    }
  ]
}

Email Verification

Verify the deliverability of an email address.

This tool tries to verify that an email address actually exists and can receive mail. It also includes checks to determine the potential riskiness of sending to a given email address.

Definition

GET https://api.maildb.io/v1/verify

Parameters

Parameter
Required
Type
Detail
email
Yes
string
The email address you wish to verify.

Example Request

curl "https://api.maildb.io/v1/verify?email=rob@maildb.io" \
  -u abcdef0123456789abcdef0123456789:

Example Response

{
  "data": {
    "email": "rob@maildb.io",
    "result": "deliverable",
    "reason": "email_accepted",
    "role": false,
    "free": false,
    "disposable": false,
    "catch_all": false,
    "mx_records": true,
    "smtp_connected": true,
    "gravatar": "https://www.gravatar.com/avatar/4dae6980044226c45dbc4739e58db8d0",
    "sources": [
      {
        "domain": "maildb.io",
        "url": "http://maildb.io/",
        "found_on": "2017-03-24T07:59:48.722102862Z"
      }
    ]
  }
}

Bulk Email Verification

Verify the deliverability of a list of email addresses.

This tool performs the same function as the email verification tool and ensures the deliverability of an email, but accepts a list of emails to process.

Upload Email List

This endpoint allows you to upload an email list, which will be analyzed and prepped for verification. This will only upload a list - to actually verify the list, you must use the /bulk/verify/:id/process endpoint.

Below are the file requirements:

  • Must be in CSV format.
  • Up to 10,000 emails allowed per list.
  • Optional columns are supported

Definition

POST https://api.maildb.io/v1/bulk/verify

Parameters

Parameter
Required
Type
Detail
file
Yes
multipart/form-data
The name of the field containing the multipart form-data for the file.

Example Request

curl "https://api.maildb.io/v1/bulk/verify?email=rob@maildb.io" \
  -u abcdef0123456789abcdef0123456789: \
  -F "file=@list.csv"

Example Response

{
  "data": {
    "id": 123,
    "filename": "list.csv",
    "uploaded": "2018-03-18T20:12:22.835915337Z",
    "started": null,
    "finished": null,
    "status": "unverified",
    "totals": {
      "emails": 1,
      "processed": 0,
      "deliverable": 0,
      "risky": 0,
      "undeliverable": 0,
      "unknown": 0,
      "role": 0,
      "free": 0,
      "disposable": 0,
      "catch_all": 0,
      "duplicate": 0
    }
  }
}

Process Email List

This endpoint starts processing the given list.

Definition

POST https://api.maildb.io/v1/bulk/verify/:id/process

Parameters

None.

Example Request

curl "https://api.maildb.io/v1/bulk/verify/123/process" \
  -u abcdef0123456789abcdef0123456789: \
  -X POST

Example Response

{
  "data": {
    "id": 123,
    "filename": "list.csv",
    "uploaded": "2018-03-18T20:12:22.835915337Z",
    "started": "2018-03-18T20:44:34.913466355Z",
    "finished": null,
    "status": "processing",
    "totals": {
      "emails": 1,
      "processed": 0,
      "deliverable": 0,
      "risky": 0,
      "undeliverable": 0,
      "unknown": 0,
      "role": 0,
      "free": 0,
      "disposable": 0,
      "catch_all": 0,
      "duplicate": 0
    }
  }
}

Get Email List Details

This endpoint retrieves the details of the given email list.

Definition

GET https://api.maildb.io/v1/bulk/verify/:id

Parameters

None.

Example Request

curl "https://api.maildb.io/v1/bulk/verify/123" \
  -u abcdef0123456789abcdef0123456789:

Example Response

{
  "data": {
    "id": 123,
    "filename": "list.csv",
    "uploaded": "2018-03-18T20:12:22.835915337Z",
    "started": "2018-03-18T20:44:34.913466355Z",
    "finished": "2018-03-18T20:44:36.078384343Z",
    "status": "verified",
    "totals": {
      "emails": 1,
      "processed": 1,
      "deliverable": 1,
      "risky": 0,
      "undeliverable": 0,
      "unknown": 0,
      "role": 0,
      "free": 0,
      "disposable": 0,
      "catch_all": 0,
      "duplicate": 0
    }
  }
}

Download Email List

This endpoint downloads the given email list in CSV format.

Definition

GET https://api.maildb.io/v1/bulk/verify/:id/download

Parameters

Parameter
Required
Type
Detail
deliverable
No
bool
Include emails that are considered deliverable.
risky
No
bool
Include emails that are considered risky.
undeliverable
No
bool
Include emails that are considered undeliverable.
unknown
No
bool
Include emails where the deliverability could not be determined.
role
No
string
Include emails that are considered role based.

Value must be either include or exclude.
free
No
string
Include emails that are considered to be from a webmail or free email service.

Value must be either include or exclude.
disposable
No
string
Include emails that are considered to be disposable or temporary.

Value must be either include or exclude.
catch_all
No
string
Include emails that are part of a catch all domain. A catch all domain accepts all email addresses, even if they don't exist, so it may be risky to send to these domains.

Value must be either include or exclude.

Example Request

curl "https://api.maildb.io/v1/bulk/verify/123" \
  -u abcdef0123456789abcdef0123456789:

Example Response

The response will be the file data in CSV format.

Delete Email List

This endpoint deletes the given email list.

Definition

DELETE https://api.maildb.io/v1/bulk/verify/:id

Parameters

None.

Example Request

curl "https://api.maildb.io/v1/bulk/verify/123" \
  -u abcdef0123456789abcdef0123456789: \
  -X DELETE

Example Response

{
  "data": {
    "id": 123,
    "filename": "list.csv",
    "uploaded": "2018-03-18T20:12:22.835915337Z",
    "started": "2018-03-18T20:44:34.913466355Z",
    "finished": "2018-03-18T20:44:36.078384343Z",
    "status": "verified",
    "totals": {
      "emails": 1,
      "processed": 1,
      "deliverable": 1,
      "risky": 0,
      "undeliverable": 0,
      "unknown": 0,
      "role": 1,
      "free": 0,
      "disposable": 0,
      "catch_all": 0,
      "duplicate": 0
    }
  }
}