MailSlurp API API Reference

Documentation for MailSlurp's public REST API.

Send and receive email from ephemeral email addresses via REST. Test email signup, verification codes, transactional-mail and more.

About

MailSlurp is a SAAS API for sending and receiving emails from ephemeral email inboxes. These inboxes can be created on the fly and each has a unique email address.

Why

MailSlurp was built for testing software or processes that interact with email in some way. For more information see the homepage.

Usage

HTTP API

You can call the MailSlurp API from any HTTP client in any language. HTTP endpoints are documented here.

Official SDKs

Or you use one of the official generated SDK Libraries.

Custom SDKs

You can also compile your own library with SwaggerCodegen and the Swagger Spec.

Demo application

Lastly, there is an interactive GUI available at demo.mailslurp.com for testing requests.

Authentication

An API Key must be passed as a header in all requests. To get an API Key sign up and log in to the MailSlurp Dashboard web app.

Use test as an API Key when using the demo application.

Conceptual Overview

MailSlurp conceptual overview diagram

Terminology

  • Inbox
    • A unique email address
    • Unlimited in number
    • Can send and receive emails
  • Email
    • Belongs to an inbox
    • Contains summary and body
    • Raw content stored on S3

Example operation

  • Before you send or receive an email you need to create an inbox
  • It is recommended to create a new empty inbox for each test case run
  • The inbox email address is returned with the response for the GetInbox and CreateInbox operations.
  • You can send an email (from your application or MailSlurp) to that address and it will be saved in the matching inbox
  • To get the email, ListEmails in the inbox and get a list of the current emails. Then GetEmail by the id given.
  • Emails are asynchronous so it is highly recommended to use the minCount parameter when using ListEmails so that MailSlurp retries the database until your expected count is met. This means you should increase your request timeout accordingly.

Support

Issues

If you encounter issues please contact the developers or open a ticket in GitHub.

Contact

Please contact MailSlurp at any time via the support page.

API Endpoint
https://api.mailslurp.com/
Contact: contact@mailslurp.com
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 0.0.1-alpha

Authentication

API_KEY

type
apiKey
name
x-api-key
in
header

Send Emails

Send emails from inboxes you have created.

Create Inbox

POST /inboxes

Create a new ephemeral email address to send and receive from

201 Created

Created

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (201 Created)
{
  "created": "string (date-time)",
  "emailAddress": "string",
  "id": "string",
  "userId": "string"
}

Send Email

POST /inboxes/{id}

Send an email from the inbox's email address

sendEmailOptions

id: string
in path

id

Request Example
{
  "bcc": [
    "string"
  ],
  "body": "string",
  "cc": [
    "string"
  ],
  "charset": "string",
  "from": "string",
  "html": "boolean",
  "replyTo": "string",
  "subject": "string",
  "to": [
    "string"
  ]
}
201 Created

Created

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Receive Emails

Receive emails that were sent to inboxes you have created.

Get Email Content

GET /emails/{id}

Returns a email summary object with headers and content. To retrieve the raw email download it from the raw url.

id: string
in path

id

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
{
  "attachments": [
    "string"
  ],
  "bcc": [
    "string"
  ],
  "body": "string",
  "cc": [
    "string"
  ],
  "created": "string (date-time)",
  "from": [
    "string"
  ],
  "headers": "object",
  "id": "string",
  "inboxId": "string",
  "raw": "string",
  "subject": "string",
  "to": [
    "string"
  ],
  "userId": "string"
}

Get Email Analytics

GET /emails/{id}/analytics

Returns a spam analysis on a given email

id: string
in path

id

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
{
  "spamNegativityPercentage": "integer (int32)"
}

Create Inbox

POST /inboxes

Create a new ephemeral email address to send and receive from

201 Created

Created

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (201 Created)
{
  "created": "string (date-time)",
  "emailAddress": "string",
  "id": "string",
  "userId": "string"
}

List Inbox's Emails

GET /inboxes/{id}/messages

List emails that inbox has received. 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.

id: string
in path

Limit the result set, ordered by descending received date time

limit: integer (int32)
in query

limit

minCount: integer (int64)
in query

Minimum acceptable email count. Will cause request to hang (and retry) until minCount is satisfied or retryTimeout is reached.

retryTimeout: integer (int64)
in query

Maximum milliseconds to spend retrying inbox database until minCount emails are returned

since: string (date-time)
in query

Exclude emails received before this ISO 8601 date time

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
[
  {
    "created": "string (date-time)",
    "id": "string"
  }
]

Manage Entities

List and delete inboxes and emails.

Delete Email

DELETE /emails/{id}

Deletes an email and removes it from the inbox

id: string
in path

id

204 No Content

No Content

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

List Inboxes

GET /inboxes

List your inboxes

200 OK

OK

type
401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
[
  {
    "created": "string (date-time)",
    "emailAddress": "string",
    "id": "string",
    "userId": "string"
  }
]

Get Inbox

GET /inboxes/{id}

Returns an inbox's properties, including its email address

id: string
in path

id

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
{
  "created": "string (date-time)",
  "emailAddress": "string",
  "id": "string",
  "userId": "string"
}

Delete Inbox

DELETE /inboxes/{id}

Permanently delete an inbox and associated email address

id: string
in path

id

204 No Content

No Content

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

Inbox Controller

All inbox related operations.

List Inboxes

GET /inboxes

List your inboxes

200 OK

OK

type
401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
[
  {
    "created": "string (date-time)",
    "emailAddress": "string",
    "id": "string",
    "userId": "string"
  }
]

Create Inbox

POST /inboxes

Create a new ephemeral email address to send and receive from

201 Created

Created

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (201 Created)
{
  "created": "string (date-time)",
  "emailAddress": "string",
  "id": "string",
  "userId": "string"
}

Get Inbox

GET /inboxes/{id}

Returns an inbox's properties, including its email address

id: string
in path

id

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
{
  "created": "string (date-time)",
  "emailAddress": "string",
  "id": "string",
  "userId": "string"
}

Send Email

POST /inboxes/{id}

Send an email from the inbox's email address

sendEmailOptions

id: string
in path

id

Request Example
{
  "bcc": [
    "string"
  ],
  "body": "string",
  "cc": [
    "string"
  ],
  "charset": "string",
  "from": "string",
  "html": "boolean",
  "replyTo": "string",
  "subject": "string",
  "to": [
    "string"
  ]
}
201 Created

Created

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Delete Inbox

DELETE /inboxes/{id}

Permanently delete an inbox and associated email address

id: string
in path

id

204 No Content

No Content

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

List Inbox's Emails

GET /inboxes/{id}/messages

List emails that inbox has received. 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.

id: string
in path

Limit the result set, ordered by descending received date time

limit: integer (int32)
in query

limit

minCount: integer (int64)
in query

Minimum acceptable email count. Will cause request to hang (and retry) until minCount is satisfied or retryTimeout is reached.

retryTimeout: integer (int64)
in query

Maximum milliseconds to spend retrying inbox database until minCount emails are returned

since: string (date-time)
in query

Exclude emails received before this ISO 8601 date time

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
[
  {
    "created": "string (date-time)",
    "id": "string"
  }
]

Email Controller

All specific email related operations.

Get Email Content

GET /emails/{id}

Returns a email summary object with headers and content. To retrieve the raw email download it from the raw url.

id: string
in path

id

200 OK

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
{
  "attachments": [
    "string"
  ],
  "bcc": [
    "string"
  ],
  "body": "string",
  "cc": [
    "string"
  ],
  "created": "string (date-time)",
  "from": [
    "string"
  ],
  "headers": "object",
  "id": "string",
  "inboxId": "string",
  "raw": "string",
  "subject": "string",
  "to": [
    "string"
  ],
  "userId": "string"
}

Delete Email

DELETE /emails/{id}

Deletes an email and removes it from the inbox

id: string
in path

id

204 No Content

No Content

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

Get Email Analytics

GET /emails/{id}/analytics

Returns a spam analysis on a given email

id: string
in path

id

OK

401 Unauthorized

Unauthorized

403 Forbidden

Forbidden

404 Not Found

Not Found

Response Example (200 OK)
{
  "spamNegativityPercentage": "integer (int32)"
}

Schema Definitions

Email: object

attachments: string[]
string
bcc: string[]
string
body: string
cc: string[]
string
created: string (date-time)
from: string[]
string
headers: object
id: string
inboxId: string
raw: string
subject: string
to: string[]
string
userId: string
Example
{
  "attachments": [
    "string"
  ],
  "bcc": [
    "string"
  ],
  "body": "string",
  "cc": [
    "string"
  ],
  "created": "string (date-time)",
  "from": [
    "string"
  ],
  "headers": "object",
  "id": "string",
  "inboxId": "string",
  "raw": "string",
  "subject": "string",
  "to": [
    "string"
  ],
  "userId": "string"
}

EmailAnalytics: object

Analysis of an email message and its contents

spamNegativityPercentage: integer (int32)
Example
{
  "spamNegativityPercentage": "integer (int32)"
}

EmailPreview: object

Preview of an email message. For full message call the message endpoint with a given message id.

created: string (date-time)
id: string
Example
{
  "created": "string (date-time)",
  "id": "string"
}

Inbox: object

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

created: string (date-time)
emailAddress: string

The inbox's email address. Send an email to this address and the inbox will receive it

id: string
userId: string
Example
{
  "created": "string (date-time)",
  "emailAddress": "string",
  "id": "string",
  "userId": "string"
}

SendEmailOptions: object

Options for sending an email message from an inbox

bcc: string[]

Optional list of bcc destination email addresses

string
body: string

Contents of email

cc: string[]

Optional list of cc destination email addresses

string
charset: string

Optional charset

from: string

Optional from address. If not set source inbox address will be used

html: boolean
replyTo: string

Optional replyTo header

subject: string

Email subject line

to: string[]

Destination email address

string
Example
{
  "bcc": [
    "string"
  ],
  "body": "string",
  "cc": [
    "string"
  ],
  "charset": "string",
  "from": "string",
  "html": "boolean",
  "replyTo": "string",
  "subject": "string",
  "to": [
    "string"
  ]
}