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

# Mailosaur API

Mailosaur is a service for testing email and SMS flows in development and CI. The API exposes 23 endpoints to manage virtual mail servers, search and inspect inbound messages, run spam analysis, simulate replies and forwards, and provision SMS-capable test devices. It is most often used by QA engineers to assert on signup, password-reset, and OTP flows in end-to-end tests.

## For AI agents

Run end-to-end tests against email and SMS flows - search inbound messages on a Mailosaur server, inspect content and spam analysis, and forward or reply for round-trip assertions across 23 endpoints.

## Scope

Does not deliver production email or SMS, manage marketing lists, or run load tests - use for email and SMS testing in CI only.

## Capabilities

- Provision and delete virtual mail servers for isolated test environments
- Search inbound messages by sender, subject, or body content
- Inspect a delivered message including HTML, text, and attachments
- Run spam analysis against a captured message
- Forward or reply to a captured message for round-trip flow tests
- Provision SMS-capable test devices and capture inbound SMS
- Read account usage limits and transaction history

## Use cases

### End-to-End Signup and OTP Testing

Assert that a signup flow actually delivers the expected email by capturing it on a Mailosaur server in CI. POST `/messages/search` returns the matching message by recipient and subject filter, GET `/messages/{messageId}` returns the body, and the test extracts the OTP or confirmation link. Mailosaur eliminates flaky tests that depend on a real inbox.

Example prompt: POST `/messages/search` with sentTo=test+abc@mailosaur.io and subject containing "Reset", then GET `/messages/{messageId}` and extract the reset code from the HTML body.

### Spam Score Regression

Run spam analysis against every transactional email type on a release candidate to catch regressions in subject lines or content that would push deliverability down. GET `/analysis/spam/{messageId}` returns SpamAssassin score and per-rule contributions so a CI pipeline can fail the build when the score crosses a threshold.

Example prompt: After the password-reset email is captured, GET `/analysis/spam/{messageId}` and fail the test if the score exceeds 5.0.

### Inbound SMS Test Automation

Capture and assert on inbound SMS flows by provisioning Mailosaur test devices and searching for received messages by phone number or content. This is the right pattern for testing two-factor authentication flows that depend on phone-based one-time passwords without using a real SIM.

Example prompt: Provision a device via POST /devices, trigger the app's SMS OTP flow, then POST `/messages/search` with the device id and parse the OTP from the latest message.

### Round-Trip Reply and Forward Tests

Test workflows that depend on a recipient replying or forwarding a message - for example helpdesk auto-responders or distribution lists - by using POST `/messages/{messageId}/reply` and POST `/messages/{messageId}/forward.` The simulated outbound message is delivered through Mailosaur's outbound infrastructure and arrives at the system under test as if a human had pressed reply.

Example prompt: After capturing the helpdesk acknowledgement, POST `/messages/{messageId}/reply` with a body of "more info please" and assert the helpdesk re-acknowledges within 60 seconds.

### Agent-Driven QA Verification

An AI agent that drives a manual-test-replacement workflow can use Mailosaur through Jentic to spin up a test server, run a flow against the system under test, then search and assert on the captured messages. The basic-auth API key lives in your Jentic One instance, so the agent has scoped access to test inboxes without exposing credentials.

Example prompt: Create a Mailosaur server, run a signup flow, then poll `/messages/search` until the welcome email arrives and assert that the activation link is present in the body.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/servers` | Create a virtual test mail server |
| POST | `/messages/search` | Search inbound messages by criteria |
| GET | `/messages/{messageId}` | Retrieve a captured message |
| GET | `/analysis/spam/{messageId}` | Run spam analysis on a message |
| POST | `/messages/{messageId}/forward` | Forward a captured message |
| POST | `/messages/{messageId}/reply` | Reply to a captured message |
| POST | `/devices` | Provision an SMS test device |

## Key resources

- **Servers** — Virtual test mail servers with create, list, update, and delete operations
- **Messages** — Inbound message search, inspection, deletion, reply, forward, and creation
- **Analysis** — Spam analysis on a captured message
- **Files** — Attachment download by file id
- **Previews** — Email rendering previews across mail clients
- **Devices** — SMS-capable test devices for inbound SMS capture
- **Usage** — Account usage limits and transaction history

## Why Jentic

- **Setup:** Wiring the Mailosaur API by hand means setting up its HTTP basic auth with the key as username, targeting the mailosaur.com/api host, and driving its server, message, and analysis endpoints yourself. Through Jentic you install once, import Mailosaur from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Mailosaur puts the message id in the URL path (`/messages/{messageId}`, `/analysis/spam/{messageId}`), so a rule can pin your agent to reading and analysing one test message. You choose the operations it may call, so a forward or reply is not included unless you add it.
- **Credential handling:** Your Mailosaur 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 'find a test email' or 'check a message for spam', and Jentic returns the matching Mailosaur operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **MailerSend API** — Transactional email sender that pairs with Mailosaur for end-to-end test flows.
- **Mailjet API** — Transactional and marketing email provider that can be tested via Mailosaur capture.
- **Twilio Messaging** — Real SMS provider - the production equivalent of Mailosaur's test SMS.

## FAQ

### What authentication does the Mailosaur API use?

Mailosaur uses HTTP Basic authentication via the basicAuth scheme. The username is your Mailosaur API key and the password is left empty (a colon-only password). Through Jentic the API key is stored encrypted in the vault and injected into the Authorization header at execution time.

### Can I search messages received in the last minute?

Yes. POST `/messages/search` accepts criteria such as sentTo, sentFrom, subject, and body, plus a server id. It returns the most recent matching messages, which is the standard pattern for e2e tests that wait for a freshly sent email after triggering a flow.

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

Mailosaur uses a credit-based usage model rather than a per-second rate limit. GET `/usage/limits` returns your current limits and GET `/usage/transactions` returns recent consumption. The OpenAPI spec does not declare a per-second cap.

### How do I run a signup-email test through Jentic?

Search Jentic for "search mailosaur messages" to load POST `/messages/search`, then execute with the recipient address that your signup test used. Follow up with GET `/messages/{messageId}` to extract the body and assert on the activation link or OTP.

### Is the Mailosaur API free?

Mailosaur offers a free trial for evaluation; production use requires a paid plan whose monthly credit allowance is reported via `/usage/limits.` Pricing tiers are listed at https://mailosaur.com/pricing.

### Can I test inbound SMS as well as email?

Yes. POST /devices provisions an SMS-capable test device, and inbound SMS messages are captured the same way as emails - searchable through POST `/messages/search` with the device id and inspectable through GET `/messages/{messageId}.`

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

Yes. Because you run Jentic One yourself, your own rules decide which Mailosaur operations and credentials the agent may use. Since the message id sits in the URL path on operations like GET `/messages/{messageId}` and GET `/analysis/spam/{messageId}`, you can pin the agent to reading and analysing a single captured test message. You pick the operations it may call, so write actions such as POST `/messages/{messageId}/forward` or POST `/messages/{messageId}/reply` stay off limits unless you add them.