# Create an email address lookup

## Endpoint

POST

`/v1/lookup/email`

## SDK Examples

### TypeScript
```typescript
const answer = await bird.lookup.email({ email: "aisha.khan@example.com" });
// result is an open vocabulary; delivery_confidence is always comparable.
console.log(answer.result, answer.delivery_confidence);
```

### Python
```python
answer = client.lookup.email(email="aisha.khan@example.com")
# result is an open vocabulary; delivery_confidence is always comparable.
print(answer.result, answer.delivery_confidence)
```

### Go
```go
answer, err := client.Lookup.Email(context.Background(), bird.LookupEmailParams{
	Email: "aisha.khan@example.com",
})
if err != nil {
	log.Fatal(err)
}// result is an open vocabulary; delivery_confidence is always comparable.
fmt.Println(*answer.Result, *answer.DeliveryConfidence)
```

### PHP
```php
$answer = $bird->lookup->email(
    (new EmailLookupRequest())->setEmail('aisha.khan@example.com'),
);
// result is an open vocabulary; delivery_confidence is always comparable.
echo $answer->getResult(), ' ', $answer->getDeliveryConfidence();
```

### CLI
```bash
bird lookup email --email aisha.khan@example.com
```

### cURL
```bash
curl -X POST "https://us1.platform.bird.com/v1/lookup/email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "aisha.khan@example.com"
  }'
```

## Response200
```json
{
  "email": "aisha.khan@example.com",
  "valid": true,
  "result": "risky",
  "delivery_confidence": 42,
  "flags": [
    "role",
    "free_provider"
  ]
}
```

Returns a deliverability `result`, a `delivery_confidence` score, address characteristics, an assessment `reason`, and a suggested correction when available. `result` and `reason` are open vocabularies. Handle unknown values and use `delivery_confidence` as the stable fallback. Each completed lookup incurs the same charge regardless of its result.

This form keeps the address out of the URL. The [URL form](/content/docs/api/reference/get-email-lookup/index.html) performs the same lookup but cannot use an idempotency key. With this form, reuse an `Idempotency-Key` to return the stored result without another lookup or charge.

## Request Payload

`email`

- **Type**: string  
- **Required**: true

The email address to look up. Send it exactly as you hold it. The part before the `@` is case-sensitive, so the API does not lowercase it. A display-name form such as `Aisha <aisha@example.com>` is rejected rather than unwrapped.

## Response Payload

`email`

- **Type**: string  
- **Required**: true

The address that was looked up, exactly as you sent it.

`valid`

- **Type**: boolean  
- **Required**: true

The provider's validity assessment for the address. Read it with `result` and `delivery_confidence` when deciding whether to send; it does not guarantee delivery.

`result`

- **Type**: string  
- **Required**: true

The verdict on the address, and the one field to decide on.

- `valid`: the address exists and accepts mail.  
  - `neutral`: it could not be confirmed either way, usually because the receiving domain answers every recipient the same.  
  - `risky`: it probably accepts mail but is likelier than most to bounce or complain. Examples include role, disposable, and low-reputation addresses.  
  - `undeliverable`: it does not accept mail, and `reason` says why.  
  - `typo`: the address looks misspelled, and `did_you_mean` contains the correction.

Open enum: further verdicts may be added over time, so treat an unrecognized value as a future one rather than an error. Branch on the values you know and fall back on `delivery_confidence`, which is always present and always comparable.

Possible values (may grow over time): `valid`, `neutral`, `risky`, `undeliverable`, `typo`

`delivery_confidence`

- **Type**: integer  
- **Required**: true

How likely mail to this address is to be delivered, from 0 (certain not to be) to 100 (certain to be). Read it alongside `result` rather than instead of it, because the same score can sit under `neutral` or `risky` for different reasons.

`flags`

- **Type**: array of string  
- **Required**: true

Notable characteristics of the address. Empty when none apply.

`reason`

- **Type**: string

An explanation for the assessment. Can accompany an undeliverable, risky, or typo result; omitted when no recognized reason is available.

Possible values (may grow over time): `invalid_syntax`, `invalid_domain`, `invalid_recipient`, `disposable_domain`

`did_you_mean`

- **Type**: string

The address this one looks like a misspelling of. Absent unless a correction was found, which in practice means `result` is `typo`. Offer it to whoever typed the original rather than sending to it unasked, because it is a guess and the address they meant may be neither one.
