canonical: https://jentic.com/apis/mailboxlayer.com/mailboxlayer

# mailboxlayer API

mailboxlayer is a real-time email validation API from apilayer that checks deliverability before a message is queued. The two endpoints - single check and bulk check - return syntax validation, MX record verification, SMTP existence checks, catch-all detection, disposable and free-provider flags, typo suggestions, and a deliverability score. Authentication is a single access_key passed as a query parameter.

## For AI agents

Validate email addresses one at a time or in bulk before sending - get MX, SMTP, disposable, free-provider, role, and typo signals plus a numeric deliverability score in a single GET request.

## Scope

Does not send email, manage suppression lists, or track deliverability after send - use for pre-send email validation only.

## Capabilities

- Validate the syntax of an email address against RFC 5321 rules
- Verify MX records and run an SMTP existence check on the recipient host
- Flag disposable and free email providers to filter signup spam
- Suggest typo corrections (gmial.com to gmail.com) for likely misspellings
- Score deliverability from 0 to 1 to drive send/skip decisions
- Validate up to many addresses in a single bulk_check request

## Use cases

### Signup Form Validation

Stop fake and mistyped emails at the point of signup by calling /check before persisting the new user. mailboxlayer returns a structured JSON object with format_valid, mx_found, smtp_check, did_you_mean, and a numeric score so the form can either accept the address, suggest a correction, or block. A single call typically completes in under 800ms which is fast enough to run synchronously in a signup handler.

Example prompt: Call GET /check with email=jane@gmial.com and access_key=ACCESS_KEY, then if did_you_mean is non-empty, return the suggested correction to the user.

### List Hygiene for Marketing

Clean an existing email list before a marketing campaign by submitting addresses through /bulk_check. The response flags disposable, role-based, free-provider, and undeliverable addresses so marketers can suppress them before send and protect domain sender reputation. Running list hygiene weekly typically reduces hard-bounce rates from above two percent to below one percent.

Example prompt: POST a list of 500 email addresses to /bulk_check, then return the subset where score is below 0.5 or smtp_check is false for suppression.

### Lead Enrichment in CRM

Enrich every new CRM contact with deliverability metadata at create time so sales reps know which leads are reachable. The free_provider and role flags help reps prioritise corporate addresses over generic info@ aliases, and the score field can populate a custom CRM property used in lead routing rules.

Example prompt: For each new HubSpot contact created today, call /check on its email and write the score plus free_provider boolean back to the contact record.

### Agent-Driven Pre-Send Validation

An AI agent that drafts and sends outreach can validate every recipient through Jentic before triggering the send operation, gating low-score addresses from ever reaching the email provider. This pattern protects sender reputation when agents act on user-supplied or scraped contact lists.

Example prompt: Before calling sendgrid_send_email, call mailboxlayer /check on the recipient address and abort the send if score is below 0.6.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /check | Validate a single email address |
| GET | /bulk_check | Validate multiple email addresses in one call |

## Key resources

- **Single Check** — Validate one email address and return all signals in one response
- **Bulk Check** — Validate multiple email addresses in a single request

## Why Jentic

- **Setup:** Wiring mailboxlayer by hand means passing your access_key on every query string, pointing at the apilayer.net host, and parsing the validation response yourself. Through Jentic you install once, import mailboxlayer from the API Directory, store the access key once, and your agent calls it.
- **Permission scoping:** mailboxlayer exposes only read checks (/check and /bulk_check) with the target address in the request, so limit the agent to the operations it needs, such as single-address validation, and leave bulk checking out unless you add it. Every operation you allow is one you chose.
- **Credential handling:** Your mailboxlayer access key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'validate an email address' or 'check a batch of emails', and Jentic returns the matching mailboxlayer operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ZeroBounce** — Email validation provider with similar deliverability scoring and bulk verification.
- **Kickbox** — Real-time and bulk email verification with a Sendex deliverability score.
- **NeverBounce** — Email verification and list cleaning with synchronous and async bulk endpoints.
- **SendGrid Mail Send** — Transactional email sender that pairs naturally with a pre-send validator.

## FAQ

### What authentication does the mailboxlayer API use?

The mailboxlayer API uses an API key passed as the access_key query parameter on every request. Through Jentic the access_key is stored encrypted in the vault and appended at execution time, so the agent never reads or logs the raw key.

### Can I validate multiple email addresses in one call?

Yes. GET /bulk_check accepts a comma-separated list of addresses and returns one validation object per email. Bulk validation is part of the higher paid plans, while /check (single address) is available on the free tier.

### What are the rate limits for the mailboxlayer API?

Rate limits are governed by your apilayer subscription rather than per-second throttling. The free plan caps usage at 100 requests per month, while paid plans scale to 50000 or more monthly checks. The OpenAPI spec does not declare a per-second cap.

### How do I run a list-hygiene check through Jentic?

Search Jentic for "validate email addresses in bulk" to load the GET /bulk_check operation, then execute with the emails parameter set to a comma-separated list. The response array contains format_valid, smtp_check, free, disposable, and score for each address.

### Is the mailboxlayer API free?

There is a free tier capped at 100 requests per month with single-email validation only. Paid plans starting at the basic apilayer subscription unlock bulk validation, HTTPS endpoints, and higher monthly request quotas.

### Does mailboxlayer detect typos in email addresses?

Yes. The response includes a did_you_mean field that suggests a likely correction when the address looks like a misspelling of a popular domain (for example gmial.com to gmail.com). Use that field to drive a confirmation prompt at signup.

### Can I limit what my agent is allowed to do with the mailboxlayer API?

Yes. mailboxlayer exposes only two read operations, single-address validation via /check and bulk validation via /bulk_check, and because you run Jentic One yourself, your own rules decide which of these the agent may call. You can allow the agent single-address validation only and leave /bulk_check out, so it can verify one email at a time without submitting whole lists. Every operation the agent can reach is one you explicitly granted, and the encrypted access key is injected at execution time rather than exposed to the agent.