Mailosaur API
Official vendor OpenAPI document · agent-readyDeveloper ToolsTesting Qabasic23 EndpointsREST
For 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.
Use for: Create a Mailosaur server for the staging integration tests, Search for the password-reset email sent to test+abc@mailosaur.io in the last minute, Get the body of message id 9999 to assert on the OTP code, Run spam analysis on the most recent welcome email
Not supported: Does not deliver production email or SMS, manage marketing lists, or run load tests - use for email and SMS testing in CI only.
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.
Install Jentic One Beta
Connect the Mailosaur API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Mailosaur API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fmailosaur.com%2Fmailosaur" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fmailosaur.com%2Fmailosaur" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Mailosaur API.
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
Patterns agents use Mailosaur API for, with concrete tasks.
★ 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.
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.
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.
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.
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.
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
23 endpoints — mailosaur is a service for testing email and sms flows in development and ci.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Mailosaur API through Jentic.
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.
GET STARTED