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

# Mailfornet API

The Mailfornet API creates disposable email inboxes from code and reads the mail that arrives in them, built for automated tests that sign up, wait for a verification code, and type it back in. An inbox takes an optional username, one of your available domains, and a ttlMinutes lifetime of up to 1440 minutes. A wait-for-code call holds the connection open for up to 60 seconds until a message carrying a verification code or confirmation link arrives and returns just that, skipping welcome mails and newsletters. Messages can also be listed with sender and subject filters, read individually, or pushed to a registered webhook.

## For AI agents

Create disposable test inboxes with Mailfornet and wait for verification codes or confirmation links to arrive, so a sign-up test or agent can complete email verification from code.

## Scope

Does not send outbound email, host permanent mailboxes, or verify that third-party addresses exist. Use for disposable test inboxes and reading verification mail only.

## Capabilities

- Create a disposable inbox on an available domain with a username and ttlMinutes lifetime
- Wait up to 60 seconds for a verification code or confirmation link and get just that back
- List inbox messages filtered by from, subject, and since, holding open with wait instead of polling
- Read one message by id and delete an inbox with all its mail
- Register a webhook for incoming mail, send a test event, and review recent delivery attempts
- Check this month's usage and the domains your key can use

## Use cases

### AI agent completing email verification through Jentic

A browser-testing agent signs up for an app and must enter the code that gets emailed. Through Jentic it searches for 'create a test inbox', loads the Mailfornet create operation to get an address, submits it in the sign-up form, then calls the wait-for-code operation with wait set to 60 so the request returns as soon as the code arrives. The API key is injected at call time.

Example prompt: Call POST /inboxes with ttlMinutes 30, use the returned address in the sign-up form, then GET `/inboxes/{address}/code` with wait 60 and subject 'Verify'

### End-to-end sign-up tests in CI

A CI suite needs a fresh address on every run so sign-up tests never collide. Mailfornet creates an inbox per test, the wait parameter holds the request until mail arrives so there is no polling loop, and deleting the inbox removes it with its mail when the test finishes. An Idempotency-Key header lets a retried create return the original inbox.

Example prompt: Call POST /inboxes with an Idempotency-Key per test run, read mail with GET `/inboxes/{address}/messages` using wait 30, then DELETE `/inboxes/{address}`

### Password-reset and notification checks

QA wants to confirm that a password reset, invite, or receipt email is actually sent with the right subject. Mailfornet lists messages filtered by from and subject text and since a timestamp, and returns the full message by id for content checks. A registered webhook can instead push each new message to your test harness.

Example prompt: Call GET `/inboxes/{address}/messages` with subject 'Reset your password' and wait 30, then GET `/messages/{id}` to check the reset link

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/inboxes` | Create an inbox |
| GET | `/inboxes/{address}/code` | Wait for a verification code or link |
| GET | `/inboxes/{address}/messages` | List messages |
| GET | `/messages/{id}` | Read one message |
| DELETE | `/inboxes/{address}` | Delete an inbox and its mail |
| POST | `/webhooks` | Register a webhook |
| GET | `/domains` | List usable domains |

## Key resources

- **Inboxes** — Disposable addresses with a ttlMinutes lifetime, addressed by email in the URL path
- **Messages** — Mail received by an inbox, listed with filters or read by id
- **Verification codes** — Codes or confirmation links extracted from incoming mail by the wait-for-code operation
- **Webhooks** — Registered URLs for incoming mail, with test events and delivery attempts

## 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:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 93 / 100
  - Developer Experience & Jentic Compatibility: 61 / 100
  - AI-Readiness & Agent Experience: 46 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 68 / 100
- **View full report:** https://jentic.com/apis/mailfornet.com/mailfornet/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 Mailfornet by hand means a bearer key, picking a domain from the account's list, and handling long-held wait requests. Through Jentic you install once, import Mailfornet from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Mailfornet puts the inbox address in the URL path (`/inboxes/{address}/code`), so a rule can pin your agent to one inbox and the operations you pick. You choose the operations it may call, so destructive ones like deleting an inbox or removing a webhook are not included unless you add them.
- **Credential handling:** Your Mailfornet 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 'get an email verification code' or 'create a test inbox', and Jentic returns the matching Mailfornet operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Mailosaur** — Email and SMS testing with captured messages
- **MailSlurp** — Programmable inboxes for testing and automation
- **Mailtrap** — Email sandbox and sending for staging environments

## FAQ

### What authentication does the Mailfornet API use?

The Mailfornet API authenticates with an API key sent as an HTTP bearer token in the Authorization header, per its OpenAPI spec, and the spec applies it to all twelve operations. You create the key on your Mailfornet account page. Through Jentic the key is stored by your own instance and attached at call time.

### How does Mailfornet return a verification code without polling?

GET `/inboxes/{address}/code` holds the request open for up to the wait value, at most 60 seconds, until a message carrying a verification code or confirmation link arrives, then returns just that. It skips mail with neither and answers 404 code_not_found if nothing arrives in time.

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

The OpenAPI spec does not specify rate limits. GET /usage reports this month's usage for your key; check https://mailfornet.com for plan limits.

### Is there a Mailfornet MCP server?

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

### How do I create a test inbox through Jentic?

Search Jentic for 'create a disposable inbox', load the POST /inboxes operation, and run it with an optional username, a domain from GET /domains, and ttlMinutes. 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 Mailfornet API?

Yes. For example, a rule that allows POST /inboxes and GET `/inboxes/{address}/code` lets a test agent make an inbox and read its code while it cannot delete inboxes or register and remove webhooks. Jentic logs each call the agent makes.