- 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) orPOST /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.
Authorization: Bearer gm_…Validate an address
/validate{ "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. |
{
"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: nor emails:. |
| 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
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 reachesjohnsmith@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.
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 |
{ "email": "ada@acme.com", "mailbox_check": true }{
"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_foundanddisposableanswers that Groundmail had to check. - Free:
catch_allandunknown, 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
/validate/batchEach 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.
{ "emails": ["ada@acme.com", "sam@example.com"], "mailbox_check": true }{
"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
const result = await groundmail.validate('ada@gmial.com')
// result.verdict: 'valid' | 'risky' | 'invalid'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_countCLI
Exits 2 when the verdict is invalid. --mailbox runs the mailbox check; --tenant <id> attributes it to a tenant.
groundmail validate ada@gmial.com
groundmail validate ada@acme.com --mailboxMCP
The validate_email tool takes email and returns the same result. The verify_email tool runs the mailbox check (email, optional tenant).
curl
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)