# Validation

Groundmail validation checks an email address before you accept it or send to it. It works in two places:

- **On every send**, automatically: recipients that cannot receive email are held back before they bounce. See [Recipients held back by Groundmail validation](https://docs.groundmail.dev/emails#recipients-held-back-by-groundmail-validation).
- **On demand**, with `POST /validate` (one address) or `POST /validate/batch` (up to 100): for signup forms, imports and lists in your app.

Both are free. For a definite answer on whether a mailbox exists, add the [mailbox check](#mailbox-check): $0.01 per answer. Validation never sends anything to the address.

Base URL: `https://api.groundmail.dev`

---

## Authentication

```http
Authorization: Bearer gm_…
```

Any key with `emails:send` or `emails:read` (sending keys included). Call it from your server, never from the browser: the key must stay secret.

---

## Validate an address

`POST /validate`

```json
{ "email": "ada@gmial.com" }
```

### 200

```json
{
  "email": "ada@gmial.com",
  "domain": "gmial.com",
  "verdict": "risky",
  "reasons": ["possible_typo"],
  "suggestion": "ada@gmail.com",
  "disposable": false,
  "role": false
}
```

| Field | Meaning |
|-------|---------|
| `email` | The address as checked: trimmed and lowercased. |
| `domain` | Its domain, or `null` when it has none. |
| `verdict` | `valid`, `risky` or `invalid` (below). |
| `reasons` | Everything that was found, in a fixed order. Empty for a clean `valid`. |
| `suggestion` | The address with a likely-mistyped domain corrected (`gmial.com` → `gmail.com`, `yahoo.con` → `yahoo.com`), or `null`. |
| `disposable` | A throwaway-inbox service. |
| `role` | A team or queue mailbox (`info@`, `support@`, `noreply@`) rather than a person. |

### Verdicts and reasons

| `verdict` | Reasons that lead to it | What to do |
|-----------|-------------------------|------------|
| `invalid` | `syntax` (the address cannot exist), `no_mail_server` (the domain does not exist or takes no email), `mailbox_not_found` (the mailbox is known not to exist), `previously_bounced` (it hard-bounced for a Groundmail sender in the last 90 days) | Reject it, or ask for another address. Mail to it would bounce. |
| `risky` | `disposable`, `catch_all` (the domain accepts every address, so the mailbox cannot be confirmed), `possible_typo` (see `suggestion`), `likely_bot_signup` (see [Bot sign-ups](#bot-sign-ups)) | Accept it, or ask "Did you mean …?" with `suggestion`. For `likely_bot_signup`, see below. |
| `valid` | none, or only `role` | Accept it. |

`role` is informational: role mailboxes receive email, so it never changes the verdict on its own. Whether to accept disposable and role addresses is your call; Groundmail never holds them back on send.

`valid` means nothing wrong was found, not that a person reads the mailbox. Validation does not open a connection to the recipient's mail server.

### Errors

| Status | `code` | When |
|--------|--------|------|
| 400 | `validation_error` | `email` is missing or longer than 320 characters. |
| 401 | `unauthorized` | Missing or invalid API key. |
| 403 | `insufficient_scope` | The key has neither `emails:send` nor `emails:read`. |
| 429 | `rate_limited` | More than 120 requests a minute or 5,000 an hour for this key. Wait for `Retry-After`. |

A malformed address is not an error: it returns `200` with `verdict: "invalid"` and `reasons: ["syntax"]`.

---

## On a signup form

```ts
import { Groundmail } from 'groundmail'

const groundmail = new Groundmail(process.env.GROUNDMAIL_API_KEY!)

export async function checkSignupEmail(email: string) {
  const result = await groundmail.validate(email)
  if (result.verdict === 'invalid') {
    return { ok: false, message: 'That email address cannot receive email.' }
  }
  if (result.suggestion) {
    return { ok: true, message: `Did you mean ${result.suggestion}?` }
  }
  return { ok: true }
}
```

---

## Bot sign-ups

Bots fill sign-up and contact forms with addresses that belong to real people, or with random strings. Your welcome email then reaches someone who never asked for it, and that person may mark it as spam.

`likely_bot_signup` flags two patterns:

- A Gmail address stuffed with dots, such as `j.o.h.n.s.m.i.t.h@gmail.com`. Gmail ignores dots, so this reaches `johnsmith@gmail.com`. Only Gmail addresses are checked for this.
- A long run of letters with capitals in a random pattern and no digits or separators, such as `xKjFqPzLmNvB@example.com`. Pass the address as it was typed: the check reads the capitals.

This is a pattern check on the address and nothing else. It can be wrong in both directions: a real person can have an unusual address, and plenty of bots use ordinary-looking ones. So treat it as a reason to take a second look, not as proof. For example, ask the person to confirm their address before you send anything else.

### Hold them back on send

To skip sending to these addresses, opt in on the send:

```ts
await groundmail.emails.send({
  from: 'Acme <hello@acme.com>',
  to: signup.email,
  subject: 'Welcome to Acme',
  html: '<p>Thanks for signing up.</p>',
  validation: { block_bot_signups: true },
})
```

A matching recipient is held back with `reason: "likely_bot_signup"`, in the same way as any other [held-back recipient](https://docs.groundmail.dev/emails#recipients-held-back-by-groundmail-validation). If it was the only `to`, the API returns `422`.

It is off unless you set it, on each send. Use it for sign-up and welcome emails, where the person may not have asked for anything. Leave it off for password resets, sign-in codes and receipts: those have to reach a real person with an unusual address.

---

## Mailbox check {#mailbox-check}

The free check catches addresses that cannot work, but `valid` only means nothing was wrong with the address and its domain. The mailbox check also confirms that the mailbox itself exists. Use it when your app imports or collects addresses for its users, for example the contact lists in a newsletter feature.

```json
{ "email": "ada@acme.com", "mailbox_check": true }
```

The response is the usual result plus two fields:

```json
{
  "email": "ada@acme.com",
  "domain": "acme.com",
  "verdict": "valid",
  "reasons": [],
  "suggestion": null,
  "disposable": false,
  "role": false,
  "mailbox": "exists",
  "billed": true
}
```

| `mailbox` | Meaning | Verdict |
|-----------|---------|---------|
| `exists` | The mailbox exists. | Unchanged |
| `not_found` | The mailbox or its domain does not exist. `reasons` includes `mailbox_not_found` (or `no_mail_server`, `syntax`, `previously_bounced`). | `invalid` |
| `catch_all` | The domain accepts mail for every address, so this mailbox cannot be confirmed. | `risky` |
| `disposable` | A throwaway-inbox service. | `risky` |
| `unknown` | No answer this time, usually because the recipient's mail server did not respond. Try again later. | Unchanged |

### Pricing

**$0.01 for each answer with `billed: true`**, on your monthly invoice as its own line, "Mailbox checks".

- Billed: `exists`, `not_found` and `disposable` answers that Groundmail had to check.
- Free: `catch_all` and `unknown`, and any address the free check already settles (bad syntax, a domain with no mail server, a recent hard bounce, a disposable domain, or a mailbox Groundmail already knows about).
- The same address twice in one request is billed once.

It needs pay as you go or the Dedicated plan, and a key with `emails:send`. It is not available on accounts with a HIPAA BAA. On Free, `mailbox_check` returns `403` `plan_limit` with an `upgrade_url`. A [test key](https://docs.groundmail.dev/ai/safe-defaults) never charges: addresses the free check can't settle come back `unknown`.

### Limits

600 addresses a minute and 10,000 a day per account, on top of the validation rate limit. Need more? Email support@groundmail.dev.

### Platforms

Pass `tenant` (the tenant's `external_id` or id) to attribute each check to one of your customers, so you can see and pass on usage per customer. A tenant-scoped key always counts toward its own tenant.

---

## Validate up to 100 at once {#batch}

`POST /validate/batch`

```json
{ "emails": ["ada@acme.com", "sam@example.com"], "mailbox_check": true }
```

```json
{
  "data": [
    { "email": "ada@acme.com", "verdict": "valid", "mailbox": "exists", "billed": true, "...": "..." },
    { "email": "sam@example.com", "verdict": "risky", "reasons": ["catch_all"], "mailbox": "catch_all", "billed": false, "...": "..." }
  ],
  "billed_count": 1
}
```

Each address is answered as `POST /validate` would, in the order sent. Each one counts toward the key's validation rate limit (120 a minute, 5,000 an hour), so validate a large import a page of 100 at a time. With the mailbox check a page usually answers in a few seconds.

---

## SDK

```ts
const result = await groundmail.validate('ada@gmial.com')
// result.verdict: 'valid' | 'risky' | 'invalid'
```

```ts
const checked = await groundmail.validate('ada@acme.com', { mailboxCheck: true })
// checked.mailbox: 'exists' | 'not_found' | 'catch_all' | 'disposable' | 'unknown'; checked.billed

const page = await groundmail.validateBatch(emails.slice(0, 100), { mailboxCheck: true })
// page.data[i], page.billed_count
```

## CLI

```bash
groundmail validate ada@gmial.com
groundmail validate ada@acme.com --mailbox
```

Exits `2` when the verdict is `invalid`. `--mailbox` runs the mailbox check; `--tenant <id>` attributes it to a tenant.

## MCP

The `validate_email` tool takes `email` and returns the same result. The `verify_email` tool runs the mailbox check (`email`, optional `tenant`).

## curl

```bash
curl -X POST https://api.groundmail.dev/validate \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@gmial.com"}'
```

---

## On send

The send-time checks are on by default. An account owner can turn off the two that draw on what Groundmail has seen across senders (`previously_bounced` and `mailbox_not_found`) in **Settings → Suppressions**; invalid addresses and domains with no mail server are always held back. `likely_bot_signup` applies only to [sends that opt in](#hold-them-back-on-send). Held-back recipients are not added to your suppression list.

---

## OpenAPI

[`openapi/groundmail.yaml`](https://docs.groundmail.dev/openapi.yaml) (`validateEmail`, `validateEmailBatch`)
