REST API Documentation

About

MailSlurp has a simple REST API for all functionality. You can create inboxes, send, receive, and forward emails. You can also manage webhooks, domains and everything available to users.

uml

Links

API URLhttps://api.mailslurp.com
Authentication Headerx-api-key: xxxx
Swagger Spechttps://api.mailslurp.com/v2/api-docs
Swagger UIhttps://api.mailslurp.com/swagger-ui.html

Table of Contents

Security

API_KEY

apiKey API Key
Name x-api-key
In header

/attachments

POST

Summary:

Upload an attachment for sending

Description:

When sending emails with attachments first upload each attachment with this endpoint. Record the returned attachment IDs. Then use these attachment IDs in the SendEmailOptions when sending an email. This means that attachments can easily be reused.

Parameters
Name Located in Description Required Schema
uploadOptions body uploadOptions Yes UploadAttachmentOptions
Responses
Code Description Schema
201 Created [ string ]
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/attachments/multipart

POST

Summary:

Upload an attachment for sending using Multipart Form

Description:

When sending emails with attachments first upload each attachment with this endpoint. Record the returned attachment IDs. Then use these attachment IDs in the SendEmailOptions when sending an email. This means that attachments can easily be reused.

Parameters
Name Located in Description Required Schema
contentType query contentType No string
file formData file Yes file
filename query filename No string
Responses
Code Description Schema
201 Created [ string ]
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/bulk/inboxes

POST

Summary:

Bulk create Inboxes (email addresses)

Description:

Enterprise Plan Required

Parameters
Name Located in Description Required Schema
count query Number of inboxes to be created in bulk Yes integer
Responses
Code Description Schema
201 Created [ Inbox ]
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

DELETE

Summary:

Bulk Delete Inboxes

Description:

Enterprise Plan Required

Parameters
Name Located in Description Required Schema
ids body ids Yes [ string (uuid) ]
Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
Security
Security Schema Scopes
API_KEY

/bulk/send

POST

Summary:

Bulk Send Emails

Description:

Enterprise Plan Required

Parameters
Name Located in Description Required Schema
bulkSendEmailOptions body bulkSendEmailOptions Yes BulkSendEmailOptions
Responses
Code Description
201 Created
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/deleteEmail

DELETE

Summary:

Delete an email

Description:

Deletes an email

Parameters
Name Located in Description Required Schema
emailId query emailId Yes string (uuid)
Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
Security
Security Schema Scopes
API_KEY

/deleteEmailAddress

DELETE

Summary:

Delete email address and its emails

Description:

Deletes an inbox

Parameters
Name Located in Description Required Schema
inboxId query inboxId Yes string (uuid)
Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
Security
Security Schema Scopes
API_KEY

/domains

GET

Summary:

Get domains

Description:

List all custom domains you have created

Responses
Code Description Schema
200 OK [ DomainPreview ]
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

POST

Summary:

Create Domain

Description:

Link a domain that you own with MailSlurp so you can create email addresses using it. Endpoint returns DNS records used for validation. You must add these verification records to your host provider's DNS setup to verify the domain.

Parameters
Name Located in Description Required Schema
domainOptions body domainOptions Yes CreateDomainOptions
Responses
Code Description Schema
201 Created Domain plus verification records and status
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/domains/{id}

GET

Summary:

Get a domain

Description:

Returns domain verification status and tokens for a given domain

Parameters
Name Located in Description Required Schema
id path id Yes string (uuid)
Responses
Code Description Schema
200 OK Domain plus verification records and status
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

DELETE

Summary:

Delete a domain

Description:

Delete a domain. This will disable any existing inboxes that use this domain.

Parameters
Name Located in Description Required Schema
id path id Yes string (uuid)
Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
410 Gone
Security
Security Schema Scopes
API_KEY

/emails

GET

Summary:

Get all emails

Description:

Responses are paginated

Parameters
Name Located in Description Required Schema
page query Optional page index in email list pagination No integer
size query Optional page size in email list pagination No integer
Responses
Code Description Schema
200 OK Page«EmailProjection»
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

DELETE

Summary:

Delete all emails

Description:

Deletes all emails

Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
Security
Security Schema Scopes
API_KEY

/emails/{emailId}

GET

Summary:

Get Email Content

Description:

Returns a email summary object with headers and content. To retrieve the raw unparsed email use the getRawMessage endpoint

Parameters
Name Located in Description Required Schema
emailId path emailId Yes string (uuid)
Responses
Code Description Schema
200 OK Email
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

DELETE

Summary:

Delete Email

Description:

Deletes an email and removes it from the inbox

Parameters
Name Located in Description Required Schema
emailId path emailId Yes string (uuid)
Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
Security
Security Schema Scopes
API_KEY

/emails/{emailId}/attachments

GET

Summary:

Get all email attachment metadata

Description:

Returns an array of attachment metadata such as name and content-type for a given email if present.

Parameters
Name Located in Description Required Schema
emailId path emailId Yes string (uuid)
Responses
Code Description Schema
200 OK [ AttachmentMetaData ]
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/emails/{emailId}/attachments/{attachmentId}

GET

Summary:

Get email attachment

Description:

Returns the specified attachment for a given email as a byte stream (file download). Get the attachmentId from the email response.

Parameters
Name Located in Description Required Schema
apiKey query Can pass apiKey in url for this request if you wish to download the file in a browser No string
attachmentId path attachmentId Yes string
emailId path emailId Yes string (uuid)
Responses
Code Description Schema
200 OK byte
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/emails/{emailId}/attachments/{attachmentId}/metadata

GET

Summary:

Get email attachment metadata

Description:

Returns the metadata such as name and content-type for a given attachment and email.

Parameters
Name Located in Description Required Schema
attachmentId path attachmentId Yes string
emailId path emailId Yes string (uuid)
Responses
Code Description Schema
200 OK AttachmentMetaData
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/emails/{emailId}/forward

POST

Summary:

Forward Email

Description:

Forward email content to given recipients

Parameters
Name Located in Description Required Schema
emailId path emailId Yes string (uuid)
forwardEmailOptions body forwardEmailOptions Yes ForwardEmailOptions
Responses
Code Description
201 Created
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/emails/{emailId}/raw

GET

Summary:

Get Raw Email Content

Description:

Returns a raw, unparsed and unprocessed email

Parameters
Name Located in Description Required Schema
emailId path emailId Yes string (uuid)
Responses
Code Description Schema
200 OK string
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/emptyInbox

DELETE

Summary:

Delete all emails in an inbox

Description:

Deletes all emails

Parameters
Name Located in Description Required Schema
inboxId query inboxId Yes string (uuid)
Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
Security
Security Schema Scopes
API_KEY

/inboxes

GET

Summary:

List Inboxes / Email Addresses

Description:

List the inboxes you have created

Responses
Code Description Schema
200 OK [ Inbox ]
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

POST

Summary:

Create an Inbox (email address)

Description:

Create a new inbox and with a ranmdomized email address to send and receive from. Pass emailAddress parameter if you wish to use a specific email address. Creating an inbox is required before sending or receiving emails. If writing tests it is recommended that you create a new inbox during each test method so that it is unique and empty.

Parameters
Name Located in Description Required Schema
emailAddress query Optional email address including domain you wish inbox to use (eg: test123@mydomain.com). Only supports domains that you have registered and verified with MailSlurp using dashboard or createDomain method. No string
expiresAt query Optional expires at timestamp. If your plan supports this feature you can specify when an inbox should expire. If left empty inbox will exist permanently or expire when your plan dictates No dateTime
Responses
Code Description Schema
201 Created Inbox
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

DELETE

Summary:

Delete all inboxes

Description:

Permanently delete all inboxes and associated email addresses and all emails within the given inboxes

Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
Security
Security Schema Scopes
API_KEY

/inboxes/paginated

GET

Summary:

List Inboxes Paginated

Description:

List inboxes in paginated form

Parameters
Name Located in Description Required Schema
favourite query Optionally filter results for favourites only No boolean
page query Optional page index in inbox list pagination No integer
search query Optionally filter by email address like No string
size query Optional page size in inbox list pagination No integer
Responses
Code Description Schema
200 OK Page«InboxProjection»
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/inboxes/{inboxId}

GET

Summary:

Get Inbox / EmailAddress

Description:

Returns an inbox's properties, including its email address and ID.

Parameters
Name Located in Description Required Schema
inboxId path inboxId Yes string (uuid)
Responses
Code Description Schema
200 OK Inbox
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

POST

Summary:

Send Email

Description:

Send an email from the inbox's email address. Specify the email recipients and contents in the request body. See the SendEmailOptions for more information. Note the inboxId refers to the inbox's id NOT its email address

Parameters
Name Located in Description Required Schema
inboxId path inboxId Yes string (uuid)
sendEmailOptions body sendEmailOptions Yes SendEmailOptions
Responses
Code Description
201 Created
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

DELETE

Summary:

Delete Inbox / Email Address

Description:

Permanently delete an inbox and associated email address and all emails within the given inboxes

Parameters
Name Located in Description Required Schema
inboxId path inboxId Yes string (uuid)
Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
Security
Security Schema Scopes
API_KEY

/inboxes/{inboxId}/emails

GET

Summary:

List Emails in an Inbox / EmailAddress

Description:

List emails that an inbox has received. Only emails that are sent to the inbox's email address will appear in the inbox. It may take several seconds for any email you send to an inbox's email address to appear in the inbox. To make this endpoint wait for a minimum number of emails use the minCount parameter. The server will retry the inbox database until the minCount is satisfied or the retryTimeout is reached

Parameters
Name Located in Description Required Schema
inboxId path Id of inbox that emails belongs to No string (uuid)
limit query Limit the result set, ordered by descending received date time No integer
minCount query Minimum acceptable email count. Will cause request to hang (and retry) until minCount is satisfied or retryTimeout is reached. No long
retryTimeout query Maximum milliseconds to spend retrying inbox database until minCount emails are returned No long
since query Exclude emails received before this ISO 8601 date time No dateTime
Responses
Code Description Schema
200 OK [ EmailPreview ]
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/inboxes/{inboxId}/favourite

PUT

Summary:

Set inbox favourited state

Description:

Set and return new favourite state for an inbox

Parameters
Name Located in Description Required Schema
inboxId path inboxId Yes string (uuid)
setInboxFavouritedOptions body setInboxFavouritedOptions Yes SetInboxFavouritedOptions
Responses
Code Description Schema
200 OK Inbox
201 Created
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/inboxes/{inboxId}/webhooks

GET

Summary:

Get all WebHooks for an Inbox

Parameters
Name Located in Description Required Schema
inboxId path inboxId Yes string (uuid)
Responses
Code Description Schema
200 OK [ Webhook ]
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

POST

Summary:

Attach a WebHook URL to an inbox

Description:

Get notified whenever an inbox receives an email via a WebHook URL. An emailID will be posted to this URL every time an email is received for this inbox. The URL must be publicly reachable by the MailSlurp server. You can provide basicAuth values if you wish to secure this endpoint.

Parameters
Name Located in Description Required Schema
inboxId path inboxId Yes string (uuid)
webhookOptions body webhookOptions Yes CreateWebhookOptions
Responses
Code Description Schema
201 Created Webhook
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/inboxes/{inboxId}/webhooks/{webhookId}

DELETE

Summary:

Delete and disable a WebHook for an Inbox

Parameters
Name Located in Description Required Schema
inboxId path inboxId Yes string (uuid)
webhookId path webhookId Yes string (uuid)
Responses
Code Description
204 No Content
401 Unauthorized
403 Forbidden
Security
Security Schema Scopes
API_KEY

/newEmailAddress

POST

Summary:

Create new email address

Description:

Returns an Inbox with an id and an emailAddress

Responses
Code Description Schema
201 Created Inbox
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/sendEmail

POST

Summary:

Send an email from a random email address

Description:

To specify an email address first create an inbox and use that with the other send email methods

Parameters
Name Located in Description Required Schema
sendEmailOptions body sendEmailOptions Yes SendEmailOptions
Responses
Code Description
201 Created
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/waitForEmailCount

GET

Summary:

Wait for and return count number of emails

Description:

Will only wait if count is greater that the found emails in given inbox.If you need to wait for an email for a non-empty inbox see the other receive methods.

Parameters
Name Located in Description Required Schema
count query Number of emails to wait for. Must be greater that 1 No integer
inboxId query Id of the inbox we are fetching emails from No string (uuid)
timeout query Max milliseconds to wait No long
Responses
Code Description Schema
200 OK [ EmailPreview ]
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/waitForLatestEmail

GET

Summary:

Fetch inbox's latest email or if empty wait for email to arrive

Description:

Will return either the last received email or wait for an email to arrive and return that. If you need to wait for an email for a non-empty inbox see the other receive methods.

Parameters
Name Located in Description Required Schema
inboxId query Id of the inbox we are fetching emails from No string (uuid)
timeout query Max milliseconds to wait No long
Responses
Code Description Schema
200 OK Email
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/waitForMatchingEmails

POST

Summary:

Wait or return list of emails that match simple matching patterns

Description:

Results must also meet provided count. Match options allow simple CONTAINS or EQUALS filtering on SUBJECT, TO, BCC, CC, and FROM.

Parameters
Name Located in Description Required Schema
count query Number of emails to wait for. Must be greater that 1 No integer
inboxId query Id of the inbox we are fetching emails from No string (uuid)
matchOptions body matchOptions Yes MatchOptions
timeout query Max milliseconds to wait No long
Responses
Code Description Schema
200 OK [ EmailPreview ]
201 Created
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

/waitForNthEmail

GET

Summary:

Wait for or fetch the email with a given index in the inbox specified

Parameters
Name Located in Description Required Schema
inboxId query Id of the inbox we are fetching emails from No string (uuid)
index query Zero based index of the email to wait for No integer
timeout query Max milliseconds to wait No long
Responses
Code Description Schema
200 OK Email
401 Unauthorized
403 Forbidden
404 Not Found
Security
Security Schema Scopes
API_KEY

Models

AttachmentMetaData

Name Type Description Required
contentLength long Yes
contentType string Yes
id string Yes
name string Yes

BasicAuthOptions

Name Type Description Required
username string Yes
password string Yes

BulkSendEmailOptions

Bulk sending options

Name Type Description Required
inboxIds [ string (uuid) ] Inboxes to send from No
sendEmailOptions SendEmailOptions Yes

CreateDomainOptions

Options for creating a domain to use with MailSlurp. You must have ownership access to this domain in order to verify it.

Name Type Description Required
domain string The top level domain you wish to use with MailSlurp No

CreateWebhookOptions

Name Type Description Required
basicAuth BasicAuthOptions Optional basic authentication that MailSlurp should use when calling the URL No
url string Public URL (including protocol) that MailSlurp can post WebhookNotificationObjects to when an email is received No
name string No

Domain plus verification records and status

Name Type Description Required
createdAt dateTime Yes
domain string Yes
id string (uuid) Yes
isVerified boolean Yes
updatedAt dateTime Yes
userId string (uuid) Yes
verificationToken string Yes

DomainPreview

Preview object for domain entity

Name Type Description Required
createdAt dateTime Yes
domain string Yes
id string (uuid) Yes

Email

Representation of an email

Name Type Description Required
analysis EmailAnalysis No
attachments [ string ] No
bcc [ string ] No
body string No
cc [ string ] No
charset string No
createdAt dateTime Yes
from string No
headers object No
id string (uuid) Yes
inboxId string (uuid) Yes
isHTML boolean No
rawUrl string No
read boolean Has the email been viewed ever No
subject string No
to [ string ] Yes
updatedAt dateTime Yes
userId string (uuid) Yes

EmailAnalysis

Analysis of email

Name Type Description Required
dkimVerdict string No
dmarcVerdict string No
spamVerdict string No
spfVerdict string No
virusVerdict string No

EmailPreview

Preview of an email message. For full message call the email endpoints with the provided email id.

Name Type Description Required
attachments [ string ] No
bcc [ string ] No
cc [ string ] No
created dateTime Yes
createdAt dateTime Yes
id string (uuid) ID of the Email. No
read boolean No
subject string No
to [ string ] Yes

EmailProjection

Name Type Description Required
attachments [ string ] No
bcc [ string ] No
cc [ string ] No
createdAt dateTime Yes
id string (uuid) Yes
inboxId string (uuid) Yes
read boolean No
subject string No
to [ string ] Yes

ForwardEmailOptions

Options for forwarding an email

Name Type Description Required
to [ string ] Yes
subject string No
cc [ string ] No
bcc [ string ] No

Inbox

Representation of an inbox with an email address. Emails can be sent to or from this email address.

Name Type Description Required
created dateTime No
emailAddress string The inbox's email address. Send an email to this address and the inbox will receive it No
expiresAt dateTime When if ever will the inbox expire No
favourite boolean Is the inbox favourited No
id string (uuid) No
userId string (uuid) No

InboxProjection

Name Type Description Required
createdAt dateTime Yes
emailAddress string No
favourite boolean No
id string (uuid) Yes

MatchOption

Name Type Description Required
field string The email property to match on. One of SUBJECT, TO, BCC, CC or FROM No
should string What criteria to apply. CONTAIN or EQUAL. Note CONTAIN is recommended due to some SMTP servers adding new lines No
value string The value to compare to the field using EQUAL or CONTAIN No

MatchOptions

Optional filter for matching emails based on fields

Name Type Description Required
matches [ MatchOption ] 1 or more match options. Options are additive so if one does not match the email is excluded from results No

Pageable

Name Type Description Required
offset long No
pageNumber integer No
pageSize integer No
paged boolean No
sort Sort No
unpaged boolean No

Page«EmailProjection»

Name Type Description Required
content [ EmailProjection ] No
empty boolean No
first boolean No
last boolean No
number integer No
numberOfElements integer No
pageable Pageable No
size integer No
sort Sort No
totalElements long No
totalPages integer No

Page«InboxProjection»

Name Type Description Required
content [ InboxProjection ] No
empty boolean No
first boolean No
last boolean No
number integer No
numberOfElements integer No
pageable Pageable No
size integer No
sort Sort No
totalElements long No
totalPages integer No

SendEmailOptions

Options for sending an email message from an inbox

Name Type Description Required
attachments [ string ] Optional list of attachment IDs to send with this email. You must first upload each attachment separately in order to obtain attachment IDs No
bcc [ string ] Optional list of bcc destination email addresses No
body string Contents of email. If HTML set isHTML to true. You can use moustache templates here if you provide a templateVariables option No
cc [ string ] Optional list of cc destination email addresses No
charset string Optional charset No
from string Optional from address. If not set source inbox address will be used No
html boolean No
isHTML boolean Optional HTML flag. If true the content-type of the email will be text/html No
replyTo string Optional replyTo header No
subject string Optional email subject line No
templateVariables object Optional map of template variables. Will replace moustache syntax variables in subject or body with the associated values No
to [ string ] List of destination email addresses. Even single recipients must be in array form. Yes

SetInboxFavouritedOptions

Name Type Description Required
state boolean No

Sort

Name Type Description Required
empty boolean No
sorted boolean No
unsorted boolean No

UploadAttachmentOptions

Options for uploading files for attachments

Name Type Description Required
base64Contents string Base64 encoded string of file contents No
contentType string Optional contentType for file. For instance application/pdf No
filename string Optional filename to save upload with No

Webhook

Representation of a webhook for an inbox.

Name Type Description Required
basicAuth boolean Does Webhook expect basic authentication No
createdAt dateTime Yes
id string (uuid) ID of the Webhook No
inboxId string (uuid) The inbox that the Webhook will be triggered by No
name string No
updatedAt dateTime Yes