# idpc email

Validate email addresses — `GET /emails`. Requires `api_key`. Each input counts as a paid lookup.

## Usage[​](#usage "Direct link to Usage")

```
idpc email [options] [query]

idpc email --file input.txt

idpc email --stdin
```

| Flag                | Description                           |
| ------------------- | ------------------------------------- |
| `-f, --file <path>` | Read one email per line               |
| `--stdin`           | Read one email per line from stdin    |
| `-o, --out <path>`  | Write CSV to a file (batch mode only) |

Exactly one of: `[query]`, `--file`, `--stdin`. Requests are tagged `cli`.

## Output[​](#output "Direct link to Output")

**Single input** (always JSON):

```
{

  "query": "support@example.com",

  "response": {

    "result": {

      "result": "deliverable",

      "deliverable": true,

      "disposable": false,

      "free": false,

      "role": true,

      "catchall": false,

      "suggestions": []

    }

  }

}
```

`result` is `"deliverable"` or `"not_deliverable"`. `suggestions` lists corrected spellings (for example a fixed typo'd domain).

**Multiple inputs** (file or stdin) emit CSV by default; pass `--json` for the `{ count, results: [{ query, response }] }` shape. CSV columns:

```
query,status,result,deliverable,disposable,free,role,catchall,suggestions
```

A row that fails its lookup doesn't abort the batch: in CSV its `status` becomes `Error: <message>`; in JSON its entry is `{ query, error: { code, message } }`. The batch still exits `0` — filter on `status` or the `error` key to find failures. Auth/permission failures (`auth_failed`, `forbidden`) are the exception: they abort the whole run since every row would fail identically.

## Agent patterns[​](#agent-patterns "Direct link to Agent patterns")

```
# Single — is it deliverable?

idpc email "support@example.com" | jq -r .response.result.result



# Batch to CSV

cat emails.txt | idpc email --stdin > emails.csv



# Batch as JSON

cat emails.txt | idpc email --stdin --json | jq '.results[] | select(.response.result.result != "deliverable")'
```

## Error codes[​](#error-codes "Direct link to Error codes")

* `missing_argument` — no `[query]`, `--file`, or `--stdin` supplied
* `auth_failed` — invalid key, or key lacks paid email validation permission
* `rate_limited` — back off and retry
* `invalid_input` — malformed request rejected by the API