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

# mailfloss API

The mailfloss API verifies email addresses, one at a time during signup or in large batches for list cleaning. A single verification returns whether the address passed all tests, a status and reason, flags for disposable, free-provider, and role-based addresses, and a suggested correction when one exists. Batch verification accepts up to 1,000,000 emails per call, runs as a job you can poll for counts of passed, risky, undeliverable, and unknown addresses, and can post results to a webhookUrl when it finishes. Running batches can be cancelled, and results are paged with page and per_page.

## For AI agents

Verify email addresses with mailfloss: check one address at signup for disposable, role-based, or undeliverable status, or clean lists of up to 1,000,000 emails per batch job.

## Scope

Does not send email, host mailing lists, or find new contact addresses. Use for verifying existing email addresses only.

## Capabilities

- Verify a single email address and read passed, status, reason, and a suggested correction
- Flag disposable, free-provider, and role-based addresses before they enter your list
- Submit up to 1,000,000 emails in one batch verification job with an optional webhookUrl
- Poll a batch job for numPassed, numRisky, numUndeliverable, and numUnknown counts
- Page through batch verification results and cancel a running job

## Use cases

### AI agent screening signups through Jentic

An onboarding agent wants to stop fake or mistyped emails before an account is created. Through Jentic it searches for 'verify an email address', loads the mailfloss verify operation, and passes the email with an optional timeout, reading passed, disposable, and suggestion in the result. The API key travels as the api_key query parameter, injected at call time.

Example prompt: Call GET /verify with email 'jane@gmial.com' and timeout 10000, and if passed is false return the suggestion to the user

### List cleaning before a campaign

A marketer about to send to an old list wants to drop dead addresses first and protect sender reputation. mailfloss accepts the full list in one batch verification call, up to 1,000,000 emails, and returns a job id. Polling the job status shows when processing has finished and how many addresses passed or were risky, undeliverable, or unknown.

Example prompt: Call POST /batch-verify with an emails array, poll GET `/batch-verify/{id}/status` until processed is true, then page GET `/batch-verify/{id}` with page 1 and per_page 1000

### Webhook-driven batch results

Polling a large job is wasteful when the results can come to you. A batch verification request can include a webhookUrl, and mailfloss posts the results there once the job completes, which the spec recommends for large lists. The job can still be checked or cancelled by id in the meantime.

Example prompt: Call POST /batch-verify with emails and webhookUrl 'https://example.com/hooks/mailfloss', and store the returned job id

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/verify` | Verify a single email address |
| POST | `/batch-verify` | Start a batch verification job |
| GET | `/batch-verify/{id}/status` | Get batch job status |
| GET | `/batch-verify/{id}` | Get batch verification results |
| POST | `/batch-verify/{id}/cancel` | Cancel a batch job |

## Key resources

- **Single verification** — One email checked with GET /verify, returning passed, status, reason, flags, and suggestion
- **Batch verification jobs** — Jobs of up to 1,000,000 emails with status counts, paged results, and cancellation

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 49 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 65 / 100
  - AI-Readiness & Agent Experience: 55 / 100
  - Agent Usability: 94 / 100
  - Security: 15 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/mailfloss.com/mailfloss/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring mailfloss by hand means appending an api_key query parameter to every URL, polling batch jobs, and paging results. Through Jentic you install once, import mailfloss from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** mailfloss puts the batch job id in the URL path (`/batch-verify/{id}`), so a rule can pin your agent to one job's status and results, while single checks run through GET /verify. You choose the operations it may call, so bulk submission and job cancellation are not included unless you add them.
- **Credential handling:** Your mailfloss API 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 'verify an email address' or 'clean an email list', and Jentic returns the matching mailfloss operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ZeroBounce** — Email validation with bulk file uploads and scoring
- **NeverBounce** — Real-time and bulk email verification
- **Kickbox** — Email verification with deliverability results
- **Mailchimp** — Email marketing platform whose audiences benefit from cleaned lists

## FAQ

### What authentication does the mailfloss API use?

The mailfloss API authenticates with an API key passed as the api_key query parameter, per its OpenAPI spec, and each of its five operations declares it. Because the key travels in the URL, keep it out of shared logs. Through Jentic the key is stored by your own instance and added to the request at call time, so the agent never sees it.

### How many emails can I verify in one mailfloss batch?

The spec allows up to 1,000,000 emails per POST /batch-verify call and up to 10 batch verification sessions running at a time. Results are paged with per_page up to 1000, defaulting to 100.

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

The OpenAPI spec does not state a request rate limit; it does cap batch size at 1,000,000 emails and running batch sessions at 10. Check https://mailfloss.com for current limits and plan credits.

### Is there a mailfloss MCP server?

You don't need an MCP server to give your agent mailfloss. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the single and batch verification operations on demand without loading another server's tool definitions into its context.

### How do I verify an email through Jentic?

Search Jentic for 'verify an email address', load the GET /verify operation, and run it with the email and an optional timeout in milliseconds, up to 60000. To run it on your own infrastructure, install Jentic One from its GitHub repo.

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

Yes. For example, a rule that allows only GET /verify lets a signup agent check single addresses while it cannot launch batch jobs that spend credits in bulk or cancel a running batch. Jentic logs each call the agent makes.