Mailosaur Messages API
Operations for finding, retrieving, creating, forwarding, replying to, and deleting the email and SMS messages received by your Mailosaur inboxes.
OpenAPI Specification
openapi: 3.0.3
info:
title: Mailosaur Analysis Messages API
description: REST API for email and SMS testing. Provides endpoints for managing test inboxes (servers), retrieving and searching messages, running deliverability checks, generating OTPs for authenticator testing, and accessing account usage data. All requests authenticate via HTTP Basic Auth using an API key.
version: 1.0.0
contact:
name: Mailosaur Support
url: https://mailosaur.com/docs/api
termsOfService: https://mailosaur.com/terms
license:
name: Commercial
url: https://mailosaur.com/terms
servers:
- url: https://mailosaur.com
description: Mailosaur production API
security:
- basicAuth: []
tags:
- name: Messages
description: Operations for finding, retrieving, creating, forwarding, replying to, and deleting the email and SMS messages received by your Mailosaur inboxes.
paths:
/api/messages:
get:
operationId: listMessages
summary: List messages
description: Returns a list of your messages in summary form. The summaries are returned sorted by received date, with the most recently-received messages appearing first.
tags:
- Messages
parameters:
- name: server
in: query
required: true
description: The unique identifier of the required inbox (server).
schema:
type: string
- name: page
in: query
description: Used alongside itemsPerPage to paginate through results. This is zero-based, meaning 0 is the first page of results.
schema:
type: integer
default: 0
- name: itemsPerPage
in: query
description: A limit on the number of results to be returned. This can be set between 1 and 1000, with the default being 50.
schema:
type: integer
default: 50
minimum: 1
maximum: 1000
- name: receivedAfter
in: query
description: Limits results to only messages received after this date/time (default 1 hour ago).
schema:
type: string
format: date-time
- name: dir
in: query
description: Optionally limits results based on the direction (Sent or Received), with the default being Received.
schema:
type: string
enum:
- Sent
- Received
responses:
'200':
description: A list of message summaries.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageListResult'
post:
operationId: createMessage
summary: Create a message
description: Creates a new message that can be sent to a verified email address. This is useful in scenarios where you want an email to trigger a workflow in your product.
tags:
- Messages
parameters:
- name: server
in: query
required: true
description: The unique identifier of the required inbox (server).
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageCreateOptions'
responses:
'200':
description: The newly-created message.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
delete:
operationId: deleteAllMessages
summary: Delete all messages
description: Permanently delete all messages within an inbox (server). This operation cannot be undone.
tags:
- Messages
parameters:
- name: server
in: query
required: true
description: The unique identifier of the inbox (server).
schema:
type: string
responses:
'204':
description: All messages were successfully deleted.
/api/messages/search:
post:
operationId: searchMessages
summary: Search messages
description: Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first.
tags:
- Messages
parameters:
- name: server
in: query
required: true
description: The unique identifier of the inbox (server) to search.
schema:
type: string
- name: page
in: query
description: Used alongside itemsPerPage to paginate through results.
schema:
type: integer
default: 0
- name: itemsPerPage
in: query
description: A limit on the number of results to be returned.
schema:
type: integer
default: 50
minimum: 1
maximum: 1000
- name: receivedAfter
in: query
description: Limits results to only messages received after this date/time.
schema:
type: string
format: date-time
- name: dir
in: query
description: Optionally limits results based on direction.
schema:
type: string
enum:
- Sent
- Received
- name: timeout
in: query
description: Specify how long to wait for a matching result in milliseconds. Default is 0 (no waiting).
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchCriteria'
responses:
'200':
description: A list of matching message summaries.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageListResult'
/api/messages/{messageId}:
get:
operationId: getMessage
summary: Get a message
description: Retrieves the detail for a single message. Must be used in conjunction with either list or search in order to get the unique identifier for the required message.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/messageId'
responses:
'200':
description: The full message detail.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
delete:
operationId: deleteMessage
summary: Delete a message
description: Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/messageId'
responses:
'204':
description: The message was successfully deleted.
/api/messages/{messageId}/forward:
post:
operationId: forwardMessage
summary: Forward a message
description: Forwards the specified message to a verified email address. This is useful for simulating a user forwarding one of your email messages.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/messageId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageForwardOptions'
responses:
'200':
description: The forwarded message.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
/api/messages/{messageId}/reply:
post:
operationId: replyToMessage
summary: Reply to a message
description: Sends a reply to the specified message. This is useful for when simulating a user replying to one of your email or SMS messages.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/messageId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageReplyOptions'
responses:
'200':
description: The reply message.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
/api/messages/{messageId}/screenshots:
post:
operationId: generateMessagePreviews
summary: Generate email previews
description: Generates screenshots of an email rendered in the specified email clients.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/messageId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PreviewRequestOptions'
responses:
'200':
description: The generated previews.
content:
application/json:
schema:
$ref: '#/components/schemas/PreviewListResult'
components:
schemas:
PreviewRequestOptions:
type: object
description: Options to use when requesting email previews.
properties:
previews:
type: array
description: A list of email clients to generate previews for.
items:
type: object
properties:
emailClient:
type: string
description: The email client identifier.
MessageHeader:
type: object
description: An email header.
properties:
field:
type: string
description: The header field name.
value:
type: string
description: The header field value.
MessageSummary:
type: object
description: A summary of a message (used in list results).
properties:
id:
type: string
description: Unique identifier for the message.
type:
type: string
enum:
- Email
- SMS
description: The type of message.
server:
type: string
description: Identifier for the inbox (server) containing this message.
from:
type: array
description: The sender(s) of the message.
items:
$ref: '#/components/schemas/MessageAddress'
to:
type: array
description: The recipient(s) of the message.
items:
$ref: '#/components/schemas/MessageAddress'
cc:
type: array
description: Carbon-copied recipients.
items:
$ref: '#/components/schemas/MessageAddress'
bcc:
type: array
description: Blind carbon-copied recipients.
items:
$ref: '#/components/schemas/MessageAddress'
received:
type: string
format: date-time
description: The date/time that this message was received.
subject:
type: string
description: The subject of the message.
attachments:
type: integer
description: The number of attachments.
MessageListResult:
type: object
description: The result of a request to list or search messages.
properties:
items:
type: array
description: A list of message summaries.
items:
$ref: '#/components/schemas/MessageSummary'
Image:
type: object
description: An image found in a message body.
properties:
src:
type: string
description: The source URL of the image.
alt:
type: string
description: The alt text of the image.
MessageCreateOptions:
type: object
description: Options to use when creating a new message.
properties:
to:
type: string
description: The email address to which the email will be sent. Must be a verified email address.
cc:
type: string
description: The email address to which the email will be CC'd to. Must be a verified email address.
from:
type: string
description: Allows for the partial override of the message's 'from' address. This must be an address ending with YOUR_SERVER.mailosaur.net.
send:
type: boolean
description: If true, email will be sent upon creation.
subject:
type: string
description: The email subject line.
text:
type: string
description: The plain text body of the message. Note that only text or html can be supplied, not both.
html:
type: string
description: The HTML body of the message. Note that only text or html can be supplied, not both.
attachments:
type: array
description: Any message attachments.
items:
$ref: '#/components/schemas/Attachment'
Attachment:
type: object
description: A file attachment on a message.
properties:
id:
type: string
description: Unique identifier for the attachment.
contentType:
type: string
description: The MIME type of the attachment.
fileName:
type: string
description: The filename of the attachment.
content:
type: string
description: The base64-encoded content of the attachment.
contentId:
type: string
description: The content ID of the attachment (for inline attachments).
length:
type: integer
description: The size of the attachment in bytes.
url:
type: string
description: URL used to download the attachment.
SearchCriteria:
type: object
description: The criteria with which to find messages during a search.
properties:
sentFrom:
type: string
description: The full email address (or phone number for SMS) from which the target message was sent.
sentTo:
type: string
description: The full email address (or phone number for SMS) to which the target message was sent.
subject:
type: string
description: The value to seek within the subject line of a target email.
body:
type: string
description: The value to seek within the body of the target message.
match:
type: string
enum:
- ALL
- ANY
default: ALL
description: If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.
MessageForwardOptions:
type: object
description: Options to use when forwarding a message.
required:
- to
properties:
to:
type: string
description: The email address to which the email will be sent. Must be a verified email address.
cc:
type: string
description: The email address to which the email will be CC'd to. Must be a verified email address.
text:
type: string
description: Any plain text to include when forwarding the message. Note that only text or html can be supplied, not both.
html:
type: string
description: Any HTML content to include when forwarding the message. Note that only text or html can be supplied, not both.
MessageContent:
type: object
description: The HTML or plain text content of a message.
properties:
links:
type: array
description: A list of hyperlinks found in the message body.
items:
$ref: '#/components/schemas/Link'
codes:
type: array
description: A list of verification codes found in the message body.
items:
type: object
properties:
value:
type: string
description: The verification code value.
images:
type: array
description: A list of images found in the message body.
items:
$ref: '#/components/schemas/Image'
body:
type: string
description: The full HTML or plain text body of the message.
MessageReplyOptions:
type: object
description: Options to use when replying to a message.
properties:
cc:
type: string
description: The email address to which the email will be CC'd to. Must be a verified email address.
text:
type: string
description: Any additional plain text content to include in the reply. Note that only text or html can be supplied, not both.
html:
type: string
description: Any additional HTML content to include in the reply. Note that only html or text can be supplied, not both.
attachments:
type: array
description: Any message attachments.
items:
$ref: '#/components/schemas/Attachment'
PreviewListResult:
type: object
description: The result of a request to generate email previews.
properties:
items:
type: array
description: A list of generated previews.
items:
$ref: '#/components/schemas/Preview'
Metadata:
type: object
description: Further metadata related to the message, including email headers.
properties:
headers:
type: array
description: A list of email headers.
items:
$ref: '#/components/schemas/MessageHeader'
ehlo:
type: string
description: The EHLO string.
mailFrom:
type: string
description: The MAIL FROM value.
rcptTo:
type: array
description: The RCPT TO values.
items:
type: string
Preview:
type: object
description: A rendered email preview screenshot.
properties:
id:
type: string
description: Unique identifier for the preview.
emailClient:
type: string
description: The email client used to render the preview.
capture:
type: string
description: The type of capture (e.g. desktop, mobile).
MessageAddress:
type: object
description: An email address or SMS phone number.
properties:
name:
type: string
description: The display name of the sender or recipient.
email:
type: string
description: The email address of the sender or recipient.
phone:
type: string
description: The phone number of the sender or recipient (SMS).
Link:
type: object
description: A hyperlink found in a message body.
properties:
href:
type: string
description: The target URL of the hyperlink.
text:
type: string
description: The display text of the hyperlink.
Message:
type: object
description: An email or SMS message processed by Mailosaur.
properties:
id:
type: string
description: Unique identifier for the message.
type:
type: string
enum:
- Email
- SMS
description: The type of message.
from:
type: array
description: The sender(s) of the message.
items:
$ref: '#/components/schemas/MessageAddress'
to:
type: array
description: The recipient(s) of the message.
items:
$ref: '#/components/schemas/MessageAddress'
cc:
type: array
description: Carbon-copied recipients for email messages.
items:
$ref: '#/components/schemas/MessageAddress'
bcc:
type: array
description: Blind carbon-copied recipients for email messages.
items:
$ref: '#/components/schemas/MessageAddress'
received:
type: string
format: date-time
description: The date/time that this message was received by Mailosaur.
subject:
type: string
description: The subject of the message.
html:
$ref: '#/components/schemas/MessageContent'
text:
$ref: '#/components/schemas/MessageContent'
attachments:
type: array
description: An array of attachment metadata for any attached files.
items:
$ref: '#/components/schemas/Attachment'
metadata:
$ref: '#/components/schemas/Metadata'
server:
type: string
description: Identifier for the inbox (server) in which the message is located.
parameters:
messageId:
name: messageId
in: path
required: true
description: The unique identifier of the message.
schema:
type: string
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic Auth using your Mailosaur API key as the username and an empty password, or your API key as both username and password.