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

# Mailsac API

Jentic publishes the only available OpenAPI specification for Mailsac API, keeping it validated and agent-ready. Mailsac provides disposable and reserved email inboxes for development and QA, exposing endpoints to fetch incoming messages, retrieve raw SMTP and parsed bodies, validate addresses, and register webhooks for inbound events. The 16-endpoint API covers address reservation, message listing and deletion, attachment-aware content retrieval, and webhook subscription so automated tests can drive sign-up flows end to end. Authentication uses the Mailsac-Key header on each request.

## For AI agents

Reserve disposable email addresses, fetch incoming messages, and subscribe to inbound-mail webhooks for automated email testing. Useful for agents that verify sign-up confirmations, password resets, and OTP codes.

## Scope

Does not send outbound email, host real production mailboxes, or scan attachments for malware - use for receiving and inspecting test email only.

## Capabilities

- Reserve a private email address and release it when the test run finishes
- Pull plain text, HTML, and raw SMTP bodies for a specific message ID
- List every message delivered to an inbox and delete them in bulk between test runs
- Validate an email address before sending a verification mail to it
- Register a webhook so an agent receives a callback the moment a message arrives
- Inspect parsed SMTP headers as JSON to assert on routing and authentication results

## Use cases

### Sign-up Confirmation Testing

End-to-end tests of registration flows need a real inbox that the application under test can email. Mailsac provides reserved disposable addresses and a polling endpoint for the inbox so a test runner can submit a sign-up form, wait for the confirmation email to land, parse the verification link out of the body, and follow it to complete account creation. Setup takes minutes per test environment.

Example prompt: Reserve qa-signup-001@mailsac.com, submit a sign-up form, poll GET `/api/addresses/{email}/messages` until the verification email arrives, then extract the link from the body.

### OTP and Password Reset Verification

QA suites that exercise password reset and one-time-code flows need to read back the codes the application sends. Mailsac exposes plain text and HTML bodies for any message in a reserved inbox, so an agent can request a reset, fetch the latest message, parse the OTP from the body, and feed it into the next step of the flow. Header inspection helps assert SPF, DKIM, and routing in the same run.

Example prompt: Trigger a password reset for user@example.com, fetch the most recent message at the Mailsac inbox, parse the 6-digit OTP, and submit it to the reset endpoint.

### Webhook-Driven Inbound Mail Processing

Long-running test environments and inbound-mail features need push delivery rather than polling. Mailsac webhooks fire when a new message arrives at a reserved address, sending the message metadata to a chosen URL. Agents can register a webhook on a per-address basis and receive immediate notification, removing the need for polling loops and reducing test latency.

Example prompt: Call POST `/api/addresses/{email}/webhooks` to register https://my-app/inbound on the reserved Mailsac address and verify the next test message triggers the callback.

### AI Agent Email Verification Loop

Agents that complete onboarding flows on behalf of users need to read confirmation emails as part of the loop. Through Jentic, an agent searches for the Mailsac operation, loads the input schema, and fetches the latest message body in three calls without manual API onboarding. The agent never holds the raw Mailsac key - Jentic injects it from the vault at execute time.

Example prompt: Use Jentic search 'fetch messages from disposable inbox', load the schema for GET `/api/addresses/{email}/messages`, and execute against the reserved address to retrieve the confirmation email.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/addresses/{email}/messages` | List messages for an email address |
| GET | `/api/addresses/{email}/messages/{messageId}` | Get a specific message metadata |
| GET | `/api/text/{email}/{messageId}` | Get plain text content of a message |
| GET | `/api/raw/{email}/{messageId}` | Get raw SMTP message |
| POST | `/api/addresses/{email}` | Reserve an email address |
| POST | `/api/addresses/{email}/webhooks` | Create a webhook for an email address |
| GET | `/api/validations/{email}` | Validate an email address |

## Key resources

- **Email Addresses** — Reserve, fetch, update, and release private email addresses on Mailsac.
- **Messages** — List, fetch, and delete messages in any reserved inbox.
- **Message Content** — Retrieve plain text, sanitized HTML, raw SMTP, and dirty HTML bodies for a message.
- **Validation** — Validate any email address for deliverability and disposable-domain status.
- **Webhooks** — Register and manage inbound-mail webhooks on a per-address basis.

## Why Jentic

- **Setup:** Wiring the Mailsac API by hand means sending your key in the Mailsac-Key header, targeting the mailsac.com host, and driving its address and message endpoints yourself. Through Jentic you install once, import Mailsac from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Mailsac puts the address in the URL path (`/api/addresses/{email}/messages`, `/api/text/{email}/{messageId}`), so a rule can pin your agent to one test address. You choose the operations it may call, so reserving an address or setting a webhook is not included unless you add it.
- **Credential handling:** Your Mailsac 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 'read a test inbox' or 'fetch a raw message', and Jentic returns the matching Mailsac operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **mailsac API Specification** — The fuller 47-endpoint Mailsac spec covering domains, attachments, account, and bulk address operations.
- **Mailtrap Email Sending API** — Mailtrap provides a sandbox SMTP and sending API used for similar email testing scenarios.
- **SendGrid Alerts API** — SendGrid handles outbound transactional sending while Mailsac receives and verifies the resulting messages.

## FAQ

### Why is there no official OpenAPI spec for Mailsac API?

Mailsac does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Mailsac API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Mailsac API use?

Mailsac uses an API key passed in the Mailsac-Key request header on every call. When you run Mailsac through Jentic the key is stored encrypted in your Jentic One instance and injected at execution time, so agents never see the raw value in their context.

### Can I read the body of a confirmation email with the Mailsac API?

Yes. Call GET `/api/text/{email}/{messageId}` for plain text, GET `/api/body/{email}/{messageId}` for sanitized HTML, or GET `/api/raw/{email}/{messageId}` for the original SMTP message including headers and attachments.

### How do I get notified when a new message arrives at a Mailsac inbox?

Register a webhook on a reserved address with POST `/api/addresses/{email}/webhooks` and Mailsac will POST message metadata to your URL on arrival, removing the need to poll GET `/api/addresses/{email}/messages.`

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

Rate limits are not declared in the OpenAPI spec - they depend on your Mailsac plan. Check your account dashboard at mailsac.com for current limits before driving high-volume test runs.

### How do I fetch the latest message for an inbox through Jentic?

Run pip install jentic, then search for 'list messages from disposable inbox', load the schema for GET `/api/addresses/{email}/messages`, and execute with the reserved address. Jentic returns the message list without the agent ever handling the API key.

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

Yes. Because you self-host Jentic One, your own rules decide which Mailsac operations and credentials the agent may use. Mailsac puts the address in the URL path, as in `/api/addresses/{email}/messages` and `/api/text/{email}/{messageId}`, so a rule can pin your agent to a single test inbox. You also choose which operations it may call, so reserving an address or creating a webhook stays out of reach unless you explicitly allow it.