Markdown

Validation

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

Updated Nov 17, 20266 min read

  • On every send, automatically: recipients that cannot receive email are held back before they bounce. See 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: $0.01 per answer. Validation never sends anything to the address.

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

Authentication

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.

HTTP
Authorization: Bearer gm_…

Validate an address

POST/validate
JSON
{ "email": "ada@gmial.com" }

200

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.
JSON
{
  "email": "ada@gmial.com",
  "domain": "gmial.com",
  "verdict": "risky",
  "reasons": ["possible_typo"],
  "suggestion": "ada@gmail.com",
  "disposable": false,
  "role": false
}

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) 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

TypeScript
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:

A matching recipient is held back with reason: "likely_bot_signup", in the same way as any other held-back recipient. 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.

TypeScript
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 },
})

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.

The response is the usual result plus two fields:

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
JSON
{ "email": "ada@acme.com", "mailbox_check": true }
JSON
{
  "email": "ada@acme.com",
  "domain": "acme.com",
  "verdict": "valid",
  "reasons": [],
  "suggestion": null,
  "disposable": false,
  "role": false,
  "mailbox": "exists",
  "billed": true
}

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 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

POST/validate/batch

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.

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
}

SDK

TypeScript
const result = await groundmail.validate('ada@gmial.com')
// result.verdict: 'valid' | 'risky' | 'invalid'
TypeScript
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

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

Terminal
groundmail validate ada@gmial.com
groundmail validate ada@acme.com --mailbox

MCP

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

curl

Terminal
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. Held-back recipients are not added to your suppression list.

OpenAPI

OpenAPI spec (validateEmail, validateEmailBatch)

Was this page helpful?