---
name: truval-email-verify
description: Verify email deliverability and validity. Use before saving user emails, sending campaigns, or making agent routing decisions based on email quality.
---

## Overview
This skill provides access to the truval.dev Email Verification API. It allows you to reliably check if an email address is syntactically valid, has active MX records, and evaluates its SMTP deliverability.

## Endpoint & Authentication
- **Base URL:** `https://api.truval.dev`
- **Verification Endpoint:** `POST /v1/email/verify`
- **Authentication:** `Authorization: Bearer <YOUR_API_KEY>`
*(Note: Never log or output the raw API key in traces, console logs, or artifacts).*

## Usage
Send a POST request with the `email` payload:
```json
{
  "email": "user@example.com"
}
```

## Response Schema (200 OK)
The API returns a JSON response outlining the status of the verification:
```json
{
  "email": "user@example.com",
  "valid": true,
  "status": "deliverable",
  "confidence": 0.97,
  "failed_check": null,
  "disposable": false,
  "role": false,
  "free_provider": false,
  "catch_all": false,
  "smtp_blocked": false,
  "mx_found": true,
  "mx_host": "mail.example.com",
  "suggestion": null,
  "latency_ms": 187
}
```

## Agent Decision Logic

Emit one of these signals when interpreting the API response:
- `GREEN_LIGHT`  → proceed
- `YELLOW_LIGHT` → proceed with caution or ask the user to confirm
- `RED_LIGHT`    → reject or request alternative address

Evaluate branches **in this order**:

1. **`suggestion != null` (evaluate first):**
   → `YELLOW_LIGHT`: prompt user "Did you mean [suggestion]?" before any other action.

2. **`disposable == true`:**
   → `RED_LIGHT`: reject. Do not accept throwaway addresses.

3. **`status` is `invalid` or `undeliverable`:**
   → `RED_LIGHT`: reject or request alternative address.

4. **`status` is `catch_all` or `catch_all == true`:**
   → `YELLOW_LIGHT`: low-certainty (confidence ~0.65). Proceed only with user confirmation, double opt-in, or downstream engagement checks. `valid: true` does **not** prove mailbox existence on catch-all.

5. **`status == "unknown"` + `smtp_blocked == true` + `confidence >= 0.75`:**
   → `YELLOW_LIGHT` (lean GREEN): major provider (Gmail, Outlook, Yahoo) — SMTP probing is blocked by the provider. Domain and MX checks passed. Do **not** treat `valid: false` as failure. Confidence ~0.75 is expected and acceptable. Allow with optional double opt-in.

6. **`status == "unknown"` + `mx_found == true` + `smtp_blocked == false`:**
   → `YELLOW_LIGHT`: SMTP was inconclusive on a real domain (common for org / Microsoft 365 domains). Typical confidence 0.50. Confirm with user or apply secondary verification. Do **not** auto-reject as invalid.

7. **`valid == true` (deliverable, catch-all handled above):**
   → `GREEN_LIGHT`: proceed. Typical confidence 0.97.

8. **Confidence fallback (after all above):**
   - `confidence >= 0.9` → `GREEN_LIGHT`
   - `confidence >= 0.7` → `YELLOW_LIGHT` (low risk, proceed with awareness)
   - `confidence >= 0.5` → `YELLOW_LIGHT` (confirm with user)
   - `confidence < 0.5`  → `RED_LIGHT` (reject or ask for different email)

### Confidence ladder
Ordinal heuristic risk signal — **not** a statistical probability of mailbox existence:
- **`0.97`**: deliverable → GREEN_LIGHT
- **`0.75`**: unknown + smtp_blocked (major providers) → YELLOW_LIGHT
- **`0.65`**: catch_all → YELLOW_LIGHT
- **`0.50`**: unknown + mx_found + not smtp_blocked (SMTP inconclusive) → YELLOW_LIGHT
- **`0.02`**: undeliverable → RED_LIGHT
- **`0.0`**: invalid path (syntax / disposable / no_mx) → RED_LIGHT

## Error Handling Guidelines
When you encounter an error, use the following action strategies:
- **`400 Bad Request`:** Check that you sent standard JSON formatting `{"email": "..."}`.
- **`401 Unauthorized`:** You are missing an API key, or the key is invalid. Output instructions for the user to retrieve their key from `https://dash.truval.dev`.
- **`402 Payment Required`:** The user has hit their hard spend cap. Do not retry. Ask them to raise limits or upgrade at `https://dash.truval.dev`.
- **`429 Too Many Requests` (`monthly_quota_exceeded`):** Free tier limit (500 units) reached. Do not retry. The `reset_at` field tells you the start of the next UTC calendar month.
- **`429 Too Many Requests` (`rate_limit_exceeded`):** The per-minute limit was exceeded. Backoff and retry *after* the `reset_at` timestamp.
- **`503 Service Unavailable`:** Temporary quota check failure. Retry shortly.

## Advanced Usage
- **Batching, Stream & Async Webhooks:** The API natively supports batching (`POST /v1/email/verify/batch`), stream mode (`POST /v1/email/verify/stream`), and async webhooks. Refer to `https://docs.truval.dev/api/email-verify`.
- **MCP Access:** Use the direct Model Context Protocol at `https://mcp.truval.dev/mcp` if tool-level integration is preferred over standard REST HTTP logic.

## Public Repositories
- SDK: [truval-dev/truval-sdk](https://github.com/truval-dev/truval-sdk)
- MCP Server: [truval-dev/truval-mcp-server](https://github.com/truval-dev/truval-mcp-server)
- Agent Skills: [truval-dev/truval-skills](https://github.com/truval-dev/truval-skills)