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

# Mailsac APIs

Mailsac provides disposable and reserved email inboxes for development, QA, and inbound-mail workflows. Its two API specs on Jentic let you reserve private addresses in bulk, fetch incoming messages with their plain text, HTML, raw SMTP, and attachment content, validate addresses, manage owned domains, and register webhooks or websocket subscriptions so tests and agents react the moment mail arrives. Both specs are OpenAPI descriptions that Jentic generates and keeps validated against the live Mailsac service.

## For AI agents

An agent can reserve disposable and reserved Mailsac inboxes (individually or up to 50 at once), poll or subscribe to incoming messages, read their text, HTML, raw SMTP, headers, and attachments, validate addresses, manage owned domains, and register inbound webhooks. This lets agents automate sign-up, password-reset, and OTP verification flows and run high-volume email QA suites.

## Scope

Use for: Receiving, inspecting, and managing disposable and reserved test email inboxes on Mailsac, including bulk reservation, attachment retrieval, owned-domain capture, and inbound webhooks.

Not supported:
- outbound email sending
- production user mailboxes
- malware attachment scanning
- SMTP relay hosting

## APIs

| API | Category | Endpoints | Description |
| --- | --- | --- | --- |
| mailsac API Specification | communications | 47 | Drive disposable and reserved Mailsac inboxes at scale: bulk-reserve addresses, fetch messages with attachments, manage owned domains, and receive inbound webhooks. |
| Mailsac API | communications | 16 | Reserve disposable email addresses, fetch incoming messages, and subscribe to inbound-mail webhooks for automated email testing. |

## Which API to use

| Need | API | Why |
| --- | --- | --- |
| Read messages and register webhooks on a single reserved inbox | mailsac | The 16-endpoint spec covers the core fetch, validate, and webhook surface for verifying sign-up, reset, and OTP flows without extra operations. |
| Bulk-reserve addresses, manage owned domains, or download attachments | mailsac-api | The 47-endpoint spec adds bulk address reservation, bulk validation, domain ownership, attachment-by-content-ID download, and websocket streams for high-volume QA. |

## Cross-API use cases

### Scale from a single verification inbox to a full QA fleet

Start on the core spec to verify one sign-up or OTP flow against a reserved inbox, then move to the fuller spec to bulk-reserve up to 50 addresses per run for a continuous-integration suite. Both share one Mailsac key, so an agent can promote a working single-inbox test to a high-volume fleet without re-authenticating.

Example prompt: Verify a sign-up flow with the core spec, then call the bulk reservation endpoint on the fuller spec to allocate 50 addresses and run the suite.

### Capture inbound mail at an owned domain and read message bodies

Use the fuller spec to verify a custom domain on the account and list every message delivered across its inboxes, then read plain text, HTML, and raw SMTP bodies through the message-content operations available on both specs. This supports wide-net inbound capture where the receiving address is generated at runtime.

Example prompt: Verify the owned domain on the fuller spec, list its recent messages, then fetch each message body and headers for the inbound processor.

### Webhook-driven inbound processing with attachment inspection

Register an inbound webhook on a reserved address using either spec so an agent is notified the moment mail arrives, then use the fuller spec to list the parts on the message and stream attachment bytes by content ID for assertion. This removes polling loops while still giving access to binary message parts.

Example prompt: Register a webhook on the reserved address, then on each callback list the attachments and download the target part by content ID to verify its MIME type.

## Why Jentic

- **Setup:** Wiring Mailsac by hand means sending your key in the right header, targeting the mailsac.com host, and tracking address, message, validation, and webhook endpoints across two specs yourself. Once Jentic One is installed, you or your agent can find and add either Mailsac spec from the Jentic directory, store the key once, and call every operation.
- **Permission scoping:** Mailsac puts the address in the URL path, so a rule in your own Jentic One instance can pin an agent to a single test inbox. You choose which operations the agent may call, so reserving addresses, the bulk private-address create, or setting a webhook is excluded unless you add it.
- **Credential handling:** Your single 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, and the same stored key serves both specs.
- **Discovery method:** Agents search the Jentic directory by intent, such as reading a test inbox, reserving addresses in bulk, or fetching 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 vendors

- **Mailtrap** — Sandbox SMTP and email-sending APIs that capture outbound mail, covering the send side of the same email-testing problem Mailsac addresses on the receive side.
- **Postmark** — Transactional email sending; pair it for outbound delivery with Mailsac for inbox-side verification in end-to-end tests.
- **SendGrid** — Outbound transactional email at scale that produces the messages Mailsac receives and asserts on during testing.

## FAQ

### How many Mailsac APIs does Jentic list and how do they differ?

Jentic lists two Mailsac specs. The 16-endpoint spec covers the core inbox surface: reserving an address, listing and reading messages, validating addresses, and registering webhooks. The 47-endpoint spec adds bulk address reservation, bulk validation, owned-domain management, attachment download by content ID, account statistics, and websocket streams. Choose the smaller spec for single-inbox verification and the larger one for high-volume or domain-level work.

### Do I need separate credentials for each Mailsac API?

No. Both specs authenticate with a single Mailsac account API key. The 47-endpoint spec sends it in the X-API-Key header and the 16-endpoint spec sends it in the Mailsac-Key header, but the underlying key is the same, so one stored credential covers every operation across both.

### What is Mailsac good for and what is it not for?

Mailsac is for receiving and inspecting email at disposable and reserved addresses: verifying sign-up confirmations, password resets, and OTP codes, capturing inbound mail at owned domains, and asserting on message content and attachments. It does not send outbound email, host production user mailboxes, or scan attachments for malware.

### Can agents work with attachments and raw message content?

Yes. Both specs expose plain text, HTML, and raw SMTP bodies for any message in a reserved inbox, plus parsed headers for asserting on routing and authentication. The 47-endpoint spec adds the ability to list the parts on a message and stream the bytes of any single attachment by content ID.

### How do agents avoid polling for new Mailsac messages?

Both specs let an agent register an inbound webhook on a reserved address so Mailsac posts message metadata to a chosen URL the moment mail arrives. The 47-endpoint spec additionally supports websocket subscriptions for live message streams, so agent runtimes can react to arrivals without tight polling loops.

### How do I use the Mailsac APIs through Jentic?

Once Jentic One is installed, you or your agent can find and add either Mailsac spec from the Jentic directory to your workspace. The agent then searches by intent, such as reading a test inbox or reserving addresses in bulk, and Jentic returns the matching operation with its input schema so the agent calls the right endpoint.