my-email-verify-api

---
name: my-email-verify-api
version: 1.0.0
description: >
  Synchronous single-address email verification — syntax + DNS + Microsoft GetCredentialType probe. Returns a verdict in <1s for ~50% of inputs; the rest get verdict='unknown' with smtp_recommended=true. The pre-send quality gate for any outbound campaign.
triggers: [email verify, email validation, deliverability, smtp, syntax check, dns mx, microsoft, mx lookup, bounce prevention]
checksum: sha256-pending
---

# MyEmailVerifyAPI

A cheap, fast quality gate for a single email address. Runs three layers in sequence: syntax check (instant) → DNS / MX lookup (sub-second) → Microsoft GetCredentialType probe (sub-second for non-Microsoft, slower for federated domains). Returns a definitive `deliverable` / `undeliverable` verdict for about half of inputs; the rest get `verdict: 'unknown'` with `smtp_recommended: true` — feed those into `verify bulk`, which SMTP-probes the uncertain addresses asynchronously.

## Capabilities
<!-- llm:start -->
Use this before any campaign send — pipe the audience members through `verify` and drop the undeliverable ones to protect your sender reputation.

Verdicts:
- **`deliverable`** — high-confidence acceptance. Safe to send.
- **`undeliverable`** — high-confidence reject. Skip. Most common causes: malformed syntax (`missing '@'`), no MX records, Microsoft positively returns "no such mailbox".
- **`unknown`** — couldn't determine cheaply. The `smtp_recommended` flag will be `true`; run those addresses through `myapi email verify bulk`, which SMTP-probes the uncertain ones (or treat as "send but watch the bounce signal").

Response shape (full check breakdown available via `--json`):
```json
{
  "email": "[email protected]",
  "verdict": "deliverable" | "undeliverable" | "unknown",
  "confidence": 0.0..1.0,
  "smtp_recommended": true,
  "checks": {
    "syntax":    { "valid": true, "detail": "missing '@'" },
    "dns":       { "valid": true, "mx_records": ["mx1.example.com", ...] },
    "microsoft": { "verdict": "...", "if_exists_result": 0, "domain_type": 4, "federated": false }
  },
  "elapsed_ms": 124
}
```

Latency notes: syntax + DNS are <100ms. Microsoft GetCredentialType is fast for non-Microsoft domains, can take 5–8s on federated (custom) Microsoft tenants while it walks redirects. Set call timeouts ≥10s for safety.
<!-- llm:end -->

## Commands
<!-- generated:start -->
| Command | What it does |
|---|---|
| `myapi email verify <email> [--json]` | Run all three verification layers on one address; print verdict + confidence + key checks |
| `myapi email verify bulk [--quick] < emails.txt` | Async batch (newline-separated stdin, ≤500 per job): cheap verdict on every address, then SMTP-probes the uncertain ones. `--quick` skips the catch-all check. Prints a `job_id` |
| `myapi email verify job <job_id> [--json]` | Poll a bulk job: status + per-address verdicts |
<!-- generated:end -->

Pass `--json` for the full check breakdown (syntax detail, MX records, Microsoft probe result). The default human render shows the verdict + a one-line summary per check that fired.

## Examples
<!-- llm:start -->
```bash
# Clear undeliverable — syntax fails instantly
myapi email verify not-an-email
# → Verdict: ✗ undeliverable  (confidence 1.00)
# → Syntax: missing '@'
# → Took: 0ms

# Generic domain — unknown verdict, MX visible, confidence 0.5
myapi email verify [email protected]
# → Verdict: ? unknown  (confidence 0.50)
# → SMTP next: yes — consider a bulk job (SMTP-probes the uncertain ones)
# → MX: gmail-smtp-in.l.google.com, alt1...

# Full breakdown
myapi email verify [email protected] --json | jq '.checks'
```

### End-to-end recipe — filter an audience before send

```bash
# Pull all members from a saved audience
AID=$(myapi audience list --json | jq -r '.[0].id')
myapi audience members $AID --limit 100 --json | jq -r '.people[].email' > emails.txt

# Verify each in parallel (modest concurrency to be polite)
while read email; do
  myapi email verify "$email" --json | jq -r '"\(.email) \(.verdict)"'
done < emails.txt | grep -v ' undeliverable$' > verified.txt
```
<!-- llm:end -->

## Notes

- `verify <email>` is the **cheap layer** (syntax → DNS → Microsoft probe). `verify bulk` completes the pipeline: it re-runs the cheap verdict, then SMTP-probes the uncertain addresses and runs catch-all detection (skip catch-all with `--quick`).
- The `confidence` field is a hint, not a guarantee. A `deliverable` verdict at 0.95 confidence is still ≈5% bounce risk in practice.
- For bulk verification use the async batch endpoint: `myapi email verify bulk < emails.txt` (one address per line) returns a `job_id`, then poll `myapi email verify job <job_id>` for status + per-address results.
- Verification is per-org; you'll get rate-limited if you blast more than ~1 req/sec per key.

Run `myapi email verify --help` for inline reference.