# Emails

Verify single emails and bulk batches via the Emailable API.

## Verify an email

```shell
curl "https://api.emailable.com/v1/verify?email=john@smith.com&api_key=YOUR_API_KEY"
```

```ruby
Emailable.verify('john@smith.com')
```

```javascript
emailable.verify('john@smith.com')
  .then((response) => {
    // asynchronously called
  });
```

```python
client.verify('john@smith.com')
```

> The above command returns JSON structured like this:

```json
{
  "accept_all": null,
  "did_you_mean": null,
  "disposable": false,
  "domain": "gmail.com",
  "duration": 0.493,
  "email": "john.smith@gmail.com",
  "first_name": "John",
  "free": true,
  "full_name": "John Smith",
  "gender": "male",
  "last_name": "Smith",
  "mailbox_full": false,
  "mx_record": "aspmx.l.google.com",
  "no_reply": false,
  "reason": "accepted_email",
  "role": false,
  "score": 100,
  "smtp_provider": "google",
  "state": "deliverable",
  "tag": null,
  "user": "john.smith"
}
```

> If a verification is taking too long, a 249 [status code](/docs/api/status-codes/) will be returned:

```json
{
  "message": "Your request is taking longer than normal. Please send your request again."
}
```

Verify a single email. If a verification request takes longer than the timeout,
you may retry this request for up to 5 minutes. After 5 minutes, further
requests will count against your usage. The verification result will be
returned when it is available.

When a test key is used, a random sample response will be returned.

### Endpoint

`GET https://api.emailable.com/v1/verify`

### Parameters

Parameter          | Required | Description
------------------ | -------- | -----------
`email`            | Yes      | The email you want verified.
`smtp`             | No       | `true` or `false`. The SMTP step takes up the majority of the API's response time. If you would like to speed up your response times, you can disable this step. However, this will significantly decrease verification accuracy. Default: `true`
`accept_all`       | No       | `true` or `false`. Whether or not an accept-all check is performed. Heavily impacts API's response time. Default: `false`
`api_key`          | No       | Your API key.
`access_token`     | No       | Your access token.
`timeout`          | No       | Optional timeout to wait for response (in seconds). Min: 2, Max: 10. Default: 5
`captcha_response` | No       | The response string from your captcha provider. Only applicable when using a public API key with a captcha.

### Response

The list of all attributes returned for each email verification. For additional details about each `state` and `reason`, [click here](/docs/email-verification/email-verification-results/results-overview/all-possible-states-and-reasons/).

Attribute      | Type     | Description
-------------- | -------- | -----------
`accept_all`   | Boolean  | Whether the mail server used to verify indicates that all addresses are deliverable regardless of whether or not the email is valid.
`did_you_mean` | String   | A suggested correction for a common misspelling.
`disposable`   | Boolean  | Whether this email is hosted on a disposable or temporary email service.
`domain`       | String   | The domain of the email. (e.g. The domain for john.smith@gmail.com would be `gmail.com`)
`duration`     | Float    | The length of time (in seconds) spent verifying this email.
`email`        | String   | The email that was verified.
`first_name`   | String   | The possible first name of the user.
`free`         | Boolean  | Whether the email is hosted by a free email provider.
`full_name`    | String   | The possible full name of the user.
`gender`       | String   | The possible gender of the user.
`last_name`    | String   | The possible last name of the user.
`mailbox_full` | Boolean  | The mailbox is currently full and emails may not be delivered.
`mx_record`    | String   | The address of the mail server used to verify the email.
`no_reply`     | Boolean  | An address that indicates it should not be replied to.
`reason`       | String   | The reason for the associated `state`.
`role`         | Boolean  | Whether the email is considered a role address. (e.g. `support`, `info`, etc.)
`score`        | Integer  | The score of the verified email.
`smtp_provider`| String   | The SMTP provider of the verified email's domain.
`state`        | String   | The state of the verified email. (e.g. `deliverable`, `undeliverable`, `risky`, `unknown`)
`tag`          | String   | The tag part of the verified email. (e.g. The tag for john.smith+example@gmail.com would be `example`)
`user`         | String   | The user part of the verified email. (e.g. The user for john.smith@gmail.com would be `john.smith`)

## Verify a batch of emails

```shell
curl -X POST "https://api.emailable.com/v1/batch" \
-d "emails=tim@smith.com,john@smith.com" \
-d "url=http://example.com/callback" \
-d "api_key=YOUR_API_KEY"
```

```ruby
emails = ['tim@smith.com', 'john@smith.com']
callback = 'http://example.com/callback'
batch = Emailable::Batch.new(emails)
batch.verify(url: callback)
```

```javascript
const emails = ['tim@smith.com', 'john@smith.com'];
const callback = 'http://example.com/callback';

emailable.batches.verify(emails, { url: callback })
  .then((response) => {
    // asynchronously called
  });
```

```python
emails = ['tim@smith.com', 'john@smith.com']
callback = 'http://example.com/callback'
client.batch(emails, {"url": callback})
```

> The above command returns JSON structured like this:

```json
{
  "message": "Batch successfully created.",
  "id": "5cf6dd30093f96d2ac34bb0a"
}
```

Verify a batch of emails. The emails should be sent as a parameter `emails` and
should be separated by commas. Up to 50,000 emails can be sent per batch. For
enterprise accounts, larger batches may be requested by
<a href="javascript:$crisp.push(['do', 'chat:open']);">contacting support</a>.

Data can be encoded as `application/x-www-form-urlencoded`,
`multipart/form-data`, or `application/json`.

Please ensure that all parameters are sent in the HTTP request body, not in the
query string portion of the URL.

If a URL is specified, the results will be sent to it via HTTP POST upon batch
completion. The body will be JSON data, identical to the output from the batch
status (`GET /v1/batch`) endpoint below. The endpoint should return an HTTP 200
status. If any other status code is returned, the results will continue to be
sent hourly until a 200 status code is returned, or until 3 days have passed
since the batch finished verifying.

When a test key is used, a successful batch creation response will be
returned along with an example batch id. Additionally, it is possible to simulate certain API responses when using a test key by utilizing the `simulate` parameter.

### Endpoint

`POST https://api.emailable.com/v1/batch`

### Parameters

Parameter        | Required | Description
---------------- | -------- | -----------
`emails`         | Yes      | A comma separated list of emails.
`url`            | No       | A URL that will receive the batch results via HTTP POST.
`api_key`        | No       | Your API key.
`access_token`   | No       | Your access token.
`response_fields`| No       | A comma separated list of fields to include in the response. If nothing is specified, all fields will be returned. Valid fields are `accept_all`, `did_you_mean`, `disposable`, `domain`, `email`, `first_name`, `free`, `full_name`, `gender`, `last_name`, `mailbox_full`, `mx_record`, `no_reply`, `reason`, `role`, `score`, `smtp_provider`, `state`, `tag`, and `user`.
`retries`        | No       | Defaults to true. Retries increase accuracy by automatically retrying verification when our system receives certain responses from mail servers. To speed up verification, you can disable this by setting retries to `false`; however, doing so may increase the number of unknown responses.
`simulate`       | No       | Used to simulate certain responses from the API while using a test key. Valid options are `generic_error`, `insufficient_credits_error`, `payment_error`, and `card_error`.

### Response

Attribute      | Type     | Description
-------------- | -------- | -----------
`message`      | String   | A message about your batch.
`id`           | String   | The unique ID of the batch.

## Get the status of a batch

```shell
curl "https://api.emailable.com/v1/batch?api_key=YOUR_API_KEY&id=5cf6dd30093f96d2ac34bb0a"
```

```ruby
batch = Emailable::Batch.new('5cf6dd30093f96d2ac34bb0a')
batch.status
```

```javascript
const id = '5cf6dd30093f96d2ac34bb0a';

emailable.batches.status(id)
  .then((response) => {
    // asynchronously called
  });
```

```python
client.batch_status('5cf6dd30093f96d2ac34bb0a')
```

> If your batch is incomplete, a message will be returned, as well as the batch's progress if it is processing:

```json
{
  "message": "Your batch is being processed.",
  "processed": 1,
  "total": 2
}
```

> If you choose to include partial results, you will get emails and counts in your response, even if the batch is still processing (keep an eye on `total_counts.processed` and `total_counts.total` for progress):

```json
{
  "message": "Your batch is being processed.",
  "emails": [
    {
      "accept_all": false,
      "did_you_mean": null,
      "disposable": false,
      "domain": "gmail.com",
      "email": "john.smith@gmail.com",
      "first_name": "John",
      "free": true,
      "full_name": "John Smith",
      "gender": "male",
      "last_name": "Smith",
      "mailbox_full": false,
      "mx_record": "aspmx.l.google.com",
      "no_reply": false,
      "reason": "accepted_email",
      "role": false,
      "score": 95,
      "smtp_provider": "google",
      "state": "deliverable",
      "tag": null,
      "user": "john.smith"
    }
  ],
  "id": "5cf6dd30093f96d2ac34bb0a",
  "reason_counts": {
    "accepted_email": 1,
    "invalid_domain": 0,
    "invalid_email": 0,
    "invalid_smtp": 0,
    "low_deliverability": 0,
    "low_quality": 0,
    "no_connect": 0,
    "rejected_email": 0,
    "timeout": 0,
    "unavailable_smtp": 0,
    "unexpected_error": 0
  },
  "total_counts": {
    "deliverable": 1,
    "processed": 1,
    "risky": 0,
    "total": 2,
    "undeliverable": 0,
    "unknown": 0,
    "duplicate": 0
  }
}
```

> When the batch completes, it will be indicated in the message field, and the results will be returned.

> Up to 1,000 emails:

```json
{
  "emails": [
    {
      "accept_all": false,
      "did_you_mean": null,
      "disposable": false,
      "domain": "gmail.com",
      "email": "john.smith@gmail.com",
      "first_name": "John",
      "free": true,
      "full_name": "John Smith",
      "gender": "male",
      "last_name": "Smith",
      "mailbox_full": false,
      "mx_record": "aspmx.l.google.com",
      "no_reply": false,
      "reason": "accepted_email",
      "role": false,
      "score": 95,
      "smtp_provider": "google",
      "state": "deliverable",
      "tag": null,
      "user": "john.smith"
    },
    {
      "accept_all": false,
      "did_you_mean": null,
      "disposable": false,
      "domain": "smith.com",
      "email": "tim@smith.com",
      "first_name": "Tim",
      "free": false,
      "full_name": "Tim",
      "gender": "male",
      "last_name": null,
      "mailbox_full": false,
      "mx_record": "mx1.smith.com",
      "no_reply": false,
      "reason": "accepted_email",
      "role": false,
      "score": 100,
      "smtp_provider": null,
      "state": "deliverable",
      "tag": null,
      "user": "tim"
    }
  ],
  "id": "5cf6dd30093f96d2ac34bb0a",
  "message": "Batch verification completed.",
  "reason_counts": {
    "accepted_email": 2,
    "invalid_domain": 0,
    "invalid_email": 0,
    "invalid_smtp": 0,
    "low_deliverability": 0,
    "low_quality": 0,
    "no_connect": 0,
    "rejected_email": 0,
    "timeout": 0,
    "unavailable_smtp": 0,
    "unexpected_error": 0
  },
  "total_counts": {
    "deliverable": 2,
    "processed": 2,
    "risky": 0,
    "total": 2,
    "undeliverable": 0,
    "unknown": 0,
    "duplicate": 0
  }
}
```

> More than 1,000 emails:

```json
{
  "id": "5cf6dd30093f96d2ac34bb0a",
  "download_file": "https://app.emailable-cdn.com/downloads/6284ee8ee1b8323ee12c201c/5cf6dd30093f96d2ac34bb0a.csv?X-Amz-Expires=3600&X-Amz-Date=20220518T130252Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA5FIXD2WWI62KKBML/20220518/us-east-1/s3/aws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=7e38682a949082d7cc7e8e2bdc09973e0fdedd858de23061447af1a32ee65779",
  "message": "Batch verification completed.",
  "reason_counts": {
    "accepted_email": 20000,
    "invalid_domain": 0,
    "invalid_email": 0,
    "invalid_smtp": 0,
    "low_deliverability": 0,
    "low_quality": 0,
    "no_connect": 0,
    "rejected_email": 0,
    "timeout": 0,
    "unavailable_smtp": 0,
    "unexpected_error": 0
  },
  "total_counts": {
    "deliverable": 20000,
    "processed": 20000,
    "risky": 0,
    "total": 20000,
    "undeliverable": 0,
    "unknown": 0,
    "duplicate": 0
  }
}
```

`GET` requests to the batch endpoint will get the current status of the batch
verification job specified in the `id` parameter.

When a credit card transaction is necessary to obtain enough credits to verify
a batch, billing related messages will be returned if there is an error. These
will be sent with a `402` response code.

When a test key is used, a random sample response will be returned for each
email in the batch. Additionally, it is possible to simulate certain API responses when using a test key by utilizing the `simulate` parameter.

### Endpoint

`GET https://api.emailable.com/v1/batch`

### Parameters

Parameter      | Required | Description
-------------- | -------- | -----------
`id`           | Yes      | The id of the batch.
`api_key`      | No       | Your API key.
`access_token` | No       | Your access token.
`partial`      | No       | A boolean value indicating whether to include partial results when a batch is still verifying. This option is only available for batches with up to 1,000 emails. Defaults to `false`.
`simulate`     | No       | Used to simulate certain responses from the API while using a test key. Valid options are `generic_error`, `importing`, `verifying`, and `paused`.

### Response

By default, all fields will be returned for each email in the response. It is possible to limit the fields that are returned by specifying the `response_fields` parameter on batch creation. See the [batch creation parameters](#parameters-1) for details.

Depending on the size of your batch, the batch status endpoint will operate in
one of two ways.

#### Up to 1,000 emails

The response will include an `emails` key that will be an array containing
responses for each email in the batch.

After 30 days, the response will no longer return the `emails` key and their
individual verification results. Only the aggregate counts for the batch will be
returned.

#### Over 1,000 emails

The response will include a `download_file` key. This will be a URL to a ZIP
compressed CSV file that contains all of the responses for each email in the
batch.

After 5 days, the response will no longer return the `download_file` key. Only
the aggregate counts for the batch will be returned.

Attribute      | Type     | Description
-------------- | -------- | -----------
`message`      | String   | A message about your batch.
`processed`    | Integer  | The number of emails that have been verified in the batch.
`total`        | Integer  | The total number of emails in your batch.
`emails`       | Array    | An array containing responses for each email in the batch. This field will only be returned for batches up to 1,000 emails. (See [single email verification](#verify-an-email) for more information on the response fields.)
`download_file`| String   | A URL for a ZIP compressed CSV file containing responses for each email in the batch. This field will only be returned for batches over 1,000 emails.
`id`           | String   | The unique ID of the batch.
`reason_counts`| Hash     | A hash with one key per possible `reason` attribute. The values are integers representing the number of emails with that reason.
`total_counts` | Hash     | A hash with one key per possible `state` attribute. The values are integers representing the number of emails with that state. In addition to the `state` keys, `total_counts` also contains keys `processed` and `total`, with values indicating the number of emails in the batch.

## Test email addresses

There are several email addresses that can be used to return specific
attributes when using a test API key. These will only work with the verify
endpoint, not the batch endpoint.

Email                            | Response
-------------------------------- | --------
deliverable@example.com          | `state` will be `deliverable`
undeliverable@example.com        | `state` will be `undeliverable`
risky@example.com                | `state` will be `risky`
unknown@example.com              | `state` will be `unknown`
role@example.com                 | `role` will be `true`
free@example.com                 | `free` will be `true`
accept-all@example.com           | `accept_all` will be `true`
disposable@example.com           | `disposable` will be `true`
slow@example.com                 | returns a `249` status code