# MailSift — Overview & Quickstart

MailSift is a fast, accurate **email verification API** and **bulk CSV validator**. A single request returns whether an address is deliverable, plus the individual signals behind that verdict (syntax, MX, SPF, DMARC, disposable, role-based, catch-all, relay, and more) and a 0–100 score.

- **Base URL:** `https://mailsift.dev/api/v1`
- **Auth:** send your API key in the `X-API-Key` header (create one in the dashboard).
- **Free tier:** 500 verification credits per account, then pay-as-you-go. Standard verification costs 1 credit per email; Deep Verification costs up to 5. One balance covers both, and there is no separate SMTP subscription.
- **Machine-readable spec:** [`/openapi.json`](https://mailsift.dev/openapi.json) (OpenAPI 3.1)

## Authentication

Every API request requires an API key, sent in the `X-API-Key` header:

```
X-API-Key: msk_your_api_key_here
```

## Quickstart

### Check your balance

```bash
curl "https://mailsift.dev/api/v1/account" \
  -H "X-API-Key: msk_your_api_key_here"
```

### Verify one email

```bash
curl "https://mailsift.dev/api/v1/verify?email=johnsmith@gmail.com" \
  -H "X-API-Key: msk_your_api_key_here"
```

### Verify one email with Deep Verification

```bash
curl "https://mailsift.dev/api/v1/verify?email=johnsmith@gmail.com&mode=deep" \
  -H "X-API-Key: msk_your_api_key_here"
```

### Verify up to 100 emails at once

```bash
curl -X POST "https://mailsift.dev/api/v1/verify/batch" \
  -H "X-API-Key: msk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"emails":["a@example.com","b@gmail.com","c@yahoo.com"]}'
```

### Verify a CSV in bulk

```bash
# 1. Upload the CSV and create a job
curl -X POST "https://mailsift.dev/api/v1/verify/bulk" \
  -H "X-API-Key: msk_your_api_key_here" \
  -F "file=@emails.csv"

# 2. Poll the job (or stream /jobs/{id}/stream for live progress)
curl "https://mailsift.dev/api/v1/jobs/{job_id}" \
  -H "X-API-Key: msk_your_api_key_here"

# 3. Download the results CSV once status is "complete"
curl "https://mailsift.dev/api/v1/jobs/{job_id}/download" \
  -H "X-API-Key: msk_your_api_key_here" -o results.csv
```

## Verification modes

Every verification endpoint takes an optional `mode`:

- **`fast`** (default) runs the standard engine: syntax, normalization, domain and DNS, MX, disposable and temp-mail detection, relay and forwarder detection, role accounts, free providers, SPF, DMARC, typo suggestions, domain intelligence, domain age, local-part risk signals, catch-all detection, and the MailSift trust score. **1 credit per email.**
- **`deep`** (Deep Verification) does all of that and then talks to the recipient's mail server over SMTP to check the mailbox itself: mailbox acceptance, recipient-specific rejection, catch-all resolution, greylisting detection, provider-specific interpretation, and STARTTLS. **Up to 5 credits per email.** Deep responses carry an extra `smtp` object.

Omitting `mode` means `fast`. Existing integrations are unchanged: same latency, same 1-credit cost, same response fields. The `smtp` object only ever appears on deep responses.

Standard verification is fast. Deep verification takes longer, because MailSift waits on the recipient's mail server, and no exact completion time is promised.

Deep verification confirms a mailbox where the receiving mail server supports it. Some providers deliberately hide mailbox existence: Yahoo and AOL accept recipients they cannot confirm, and secure gateways such as Proofpoint and Mimecast accept every recipient at the perimeter. For those, MailSift returns an honest `unknown` rather than guessing.

`mode=deep` also works on batch and bulk requests. A deep bulk job appends two columns to the results CSV: `smtp_status` and `mailbox_exists`.

See the [API Reference](https://mailsift.dev/docs/api-reference.md) for the full `smtp` field list, the credit rules, and the optional `Idempotency-Key` header.

## Verification statuses

The top-level `status` is the same in both modes and combines every signal MailSift gathered.

| Status | Meaning |
|--------|---------|
| `valid` | Strong domain and mailbox-pattern signals. Safe default pass. In deep mode, the recipient's server also accepted the mailbox and its acceptance is trustworthy. |
| `risky` | Deliverable-looking domain but suspicious local part, role-based inbox, relay, or uncertain posture. In deep mode this also covers a catch-all domain, and a provider that accepted the recipient without confirming the mailbox exists. |
| `invalid` | Domain does not exist, null MX, or another hard failure. In deep mode this also covers a recipient-specific rejection from the mail server. |
| `unknown` | Inconclusive: a transient failure or edge case. Costs 0 credits. |

Deep verification adds an `smtp` object with the mailbox-level detail. **`smtp.status` is not the overall status.** An address can be SMTP-`deliverable` and still be overall `risky` because it is disposable, a role account, or a relay. Branch your logic on the top-level `status`, and read `smtp` for the reasoning behind it.

## Next steps

- [API Reference](https://mailsift.dev/docs/api-reference.md) — every endpoint and field.
- [OpenAPI 3.1 spec](https://mailsift.dev/openapi.json) — machine-readable definition.