MailSlurp API entities and how to use them

MailSlurp API entities and how to use them

MailSlurp is an abstraction layer over regular SMTP mail servers. It has unique data structures to represent email address and messages. Here is a quick overview of the models before we see how to use them.

Looking for help with the visual dashboard? See the dashboard guide.


An inbox represents an email address. Each inbox has an id and an emailAddress associated with it.

interface Inbox {
  id: string;
  emailAddress: string;


An email represents the contents and metadata of an email received by MailSlurp.

interface Email {
  id: string;
  to: Array<string>;
  subject?: string;
  body?: string;
  // ...other fields hidden


MailSlurp extracts email attachments and stores them securely on disk. You can read meta data about attachment files

interface AttachmentMetaData {
  contentLength: number;
  contentType: string;
  name: string;
  // contents with downloadAttachment() methods


MailSlurp lets you use custom domains to send and receive email. You can only use custom domains if you registered and verified the domain.

interface Domain {
  id: string;
  userId: string;
  domain: string;
  verificationToken: string;
  // ...other fields hidden


WebHooks can be attached to inboxes you have created. WebHooks have a URL that should point to a backend service that you have access to. When emails are received by an inbox with a WebHook MailSlurp will post the ID of the email to your URL so that you can receive the emails asynchronously and at scale.


Many MailSlurp methods return collections of entities in a minimal form. For instance the getEmails() method returns a List<EmailPreview> that takes the following shape:

    "id": "123"
    "id": "456"

You are expected to use collection methods to find the entities you are looking for and then call the entity methods individually for each full entity you wish to consume. In this case you would call getEmail for each email you want to fetch fully.

Next steps

Now that we understand the key structures of MailSlurp let's create an inbox.