# Inboxes

![disposable inboxes](/assets/inboxes.svg)

MailSlurp inboxes are email addresses. Inboxes can be permanent or disposable. They can have randomly assigned addresses
or use [custom email domains](https://www.mailslurp.com/guides/custom-domains/).

Inboxes are a base entity that can have other features like [webhooks](/docs/webhooks/),
routing [rules](/docs/routing-rulesets/), [forwarding](/docs/forwarding/), and [SMTP/IMAP](/docs/imap-smtp/) access configured using
their ID.

<figure data-component="DocsVideoEmbed" class="docs-video-embed">
<iframe src="https://www.youtube-nocookie.com/embed/35cHKwGXNrI?modestbranding=1&rel=0&controls=1" title="MailSlurp documentation video" loading="lazy" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
<figcaption><a href="https://www.youtube.com/watch?v=35cHKwGXNrI">Open video on YouTube</a></figcaption>
</figure>

## Quick links

- [Inbox guide](https://www.mailslurp.com/guides/creating-inboxes/)
- [Inbox storage](/docs/storage/)

## Inbox overview

Inboxes can send and receive [emails](/docs/emails/) and [attachments](/docs/attachments/). They can be created and managed using
the [dashboard](https://app.mailslurp.com/) or [API](/docs/api/) [clients](/docs/sdks/)

## Creating inboxes

Inboxes can be configured in the MailSlurp dasbhoard or using the API.

![inbox](/assets/icons/new-inbox.png)

The default SDK create action will create an HTTP inbox with a randomly assigned email addresses.

```typescript
const inbox = await mailslurp.createInbox();
// { id: '123', emailAddress: '123@mailslurp.com' }
```

You can create more complex examples by passing inbox configuration options.

<p>See <a href="https://js.mailslurp.com/classes/InboxControllerApi.html#createInboxWithOptions">inbox creation</a> options.</p>

```typescript
const inbox = await mailslurp.inboxController.createInbox({
  description: 'My inbox',
  name: 'Joe B', // become sender name in email address
  useShortAddress: true,
  expiresIn: 5 * 60 * 1000, // expire in 5 minutes
  inboxType: CreateInboxInboxTypeEnum.SMTP_INBOX, // add smtp access
  tags: ['staging', 'test'],
});
```

### Using custom addresses

To assign a custom email address to an inbox you must use a [custom domain](/docs/custom-domains/). You can use a short email
address by with the `useShortAddress` option.

```typescript
await mailslurp.inboxController.createInbox({
  emailAddress: 'test@mydomain.com'
})
```

### Plus address aliases

Plus addressing allows you to use `+xyz` suffix in the local part of an email address. When sending emails to an inbox
you can use `+xyz` style aliases to partition received emails by the sub-address alias. See
the [plus addressing](/docs/plus-addresses/) guide for more information.

For production-style retrieval patterns, avoid broad inbox search loops when you already know the full plus address. A more stable flow is:

1. Get or create a plus-address entity from the full address (including the `+suffix`) and persist `plusAddressId` + `inboxId`.
2. Use [wait for matching entities](/docs/wait-for/) with a `TO` match against the full plus address.
3. List messages by `plusAddressId` in the inbox for deterministic results.

See:
- [Plus addressing deterministic flow](/docs/plus-addresses/#deterministic-plus-address-flow)
- [Wait for plus-addressed emails](/docs/wait-for/#wait-for-plus-addressed-emails)

Plus-address entities let you persist a specific alias and fetch messages for that alias without scanning the whole inbox.

[API endpoint: `getOrCreateInboxPlusAddress`](/docs/api/#getOrCreateInboxPlusAddress)

[API endpoint: `getInboxPlusAddressEmailsForPlusAddressId`](/docs/api/#getInboxPlusAddressEmailsForPlusAddressId)

### Virtual inboxes

You can create [mail traps](/docs/virtual-inbox/) using the `virtual` flag. This means the inbox will never send out-bound
emails. It will instead save a sent message but not send the email to any recipients.

```typescript
const mailTrap = await mailslurp.inboxController.createInboxWithOptions({
    createInboxDto: {
        virtualInbox: true,
    },
});
```

### Expiry

Inboxes can be made ephemeral using the `expiresIn` or `expiresAt` properties. All
paid [plans](https://app.mailslurp.com/pricing/) use permanent inboxes by default.

```typescript
// create an inbox that expires in 5 minutes
const inbox2 = await mailslurp.createInboxWithOptions({
  expiresIn: 5 * 60_000,
});
```

### IMAP/SMTP

Inboxes can be accessed via IMAP and SMTP using the access details for the inbox or at the account level.

```typescript
const {
    secureSmtpServerHost,
    secureSmtpServerPort,
    secureSmtpUsername,
    secureSmtpPassword,
    smtpServerHost,
    smtpServerPort,
    smtpUsername,
    smtpPassword,
    secureImapServerHost,
    secureImapServerPort,
    secureImapUsername,
    secureImapPassword,
    imapServerHost,
    imapServerPort,
    imapUsername,
    imapPassword,
    mailFromDomain,
} = await mailslurp.inboxController.getImapSmtpAccess({
    inboxId // optional inbox scope
});
```

For more information see the [IMAP/SMTP guide](/docs/imap-smtp/) or [mail app config](/docs/mail-clients/).

## Configuring address and domain

Here are some common methods for creating inboxes and configuring the email address or domain

```typescript
// when you don't care about the address (will use the default domain which may change)
const inboxWithRandomAddress = await mailslurp.inboxController.createInboxWithDefaults()
expect(inboxWithRandomAddress.emailAddress).toMatch(/.*/)

// when you want to specify the domain and randomize the part before the @
const inboxWithMailSlurpDomain = await mailslurp.inboxController.createInboxWithOptions({
  createInboxDto: {
    // you can specify a mailslurp domain or your own custom one
    // see https://api.mailslurp.com/available-domains/
    domainName: 'mailslurp.biz'
  }
})
expect(inboxWithMailSlurpDomain.domain).toEqual('mailslurp.biz');
expect(inboxWithMailSlurpDomain.localPart).toMatch(/.*/)

// you can also create with a defined address
const inboxWithSpecificAddress = await mailslurp.inboxController.createInboxWithOptions({
  createInboxDto: {
    emailAddress: `specific-address-${Date.now()}@mailslurp.biz`
  }
})
expect(inboxWithSpecificAddress.emailAddress).toMatch(/specific-address-\d+@mailslurp.biz/)

// use a random domain from a larger list of mailslurp domains
const inboxWithDomainPool= await mailslurp.inboxController.createInboxWithOptions({
  createInboxDto: {
    useDomainPool: true,
    useShortAddress: true
  }
})
expect(inboxWithDomainPool.domain).not.toContain('mailslurp.biz');
```

### All create options

For all inbox creation options see the `CreateInboxDto` schema in your integration:

<details data-component="DocsSchemaTable" class="docs-schema-table">
<summary>Show CreateInboxDto schema</summary>
<div class="docs-schema-summary">
<p>Options for creating an inbox. An inbox has a real email address that can send and receive emails. Inboxes can be permanent or expire at a given time. Inboxes are either `SMTP` or `HTTP` mailboxes. `SMTP` inboxes are processed by a mail server running at `mailslurp.mx` while `HTTP` inboxes are processed by AWS SES backed mailservers. An inbox email address is randomly assigned by default ending in either `mailslurp.com` or (if `useDomainPool` is enabled) ending in a similar domain such as `mailslurp.xyz` (selected at random). To specify an address use a custom domain: either pass the `emailAddress` options with ` @ `. To create a randomized address for your domain set the `domainName` to th...</p>
<p><a href="/docs/api/#CreateInboxDto">Open full API schema</a></p>
</div>
<div class="docs-schema-table-scroll">
<table>
<thead><tr><th>Property</th><th>Required</th><th>Type</th><th>Format</th><th>Description</th></tr></thead>
<tbody><tr><td><code>emailAddress</code></td><td>No</td><td><code>string</code></td><td></td><td>A custom email address to use with the inbox. Defaults to null. When null MailSlurp will assign a random email address to the inbox such as `123@mailslurp.com`. If you use the `useDomainPool` option when the email address is null it will generate an email address with a more varied domain ending such as `123@mailslurp.info` or `123@mailslurp.biz`. When a cu...</td></tr><tr><td><code>domainName</code></td><td>No</td><td><code>string</code></td><td></td><td>FQDN domain name for the domain you have verified. Will be appended with a randomly assigned recipient name. Use the `emailAddress` option instead to specify the full custom inbox.</td></tr><tr><td><code>domainId</code></td><td>No</td><td><code>string:uuid</code></td><td></td><td>ID of custom domain to use for email address.</td></tr><tr><td><code>name</code></td><td>No</td><td><code>string</code></td><td></td><td>Optional name of the inbox. Displayed in the dashboard for easier search and used as the sender name when sending emails.</td></tr><tr><td><code>description</code></td><td>No</td><td><code>string</code></td><td></td><td>Optional description of the inbox for labelling purposes. Is shown in the dashboard and can be used with</td></tr><tr><td><code>useDomainPool</code></td><td>No</td><td><code>boolean</code></td><td></td><td>Use the MailSlurp domain name pool with this inbox when creating the email address. Defaults to null. If enabled the inbox will be an email address with a domain randomly chosen from a list of the MailSlurp domains. This is useful when the default `@mailslurp.com` email addresses used with inboxes are blocked or considered spam by a provider or receiving se...</td></tr><tr><td><code>tags</code></td><td>No</td><td><code>string[]</code></td><td></td><td>Tags that inbox has been tagged with. Tags can be added to inboxes to group different inboxes within an account. You can also search for inboxes by tag in the dashboard UI.</td></tr><tr><td><code>expiresAt</code></td><td>No</td><td><code>string:date-time</code></td><td></td><td>Optional inbox expiration date. If null then this inbox is permanent and the emails in it won&#x27;t be deleted. If an expiration date is provided or is required by your plan the inbox will be closed when the expiration time is reached. Expired inboxes still contain their emails but can no longer send or receive emails. An ExpiredInboxRecord is created when an i...</td></tr><tr><td><code>favourite</code></td><td>No</td><td><code>boolean</code></td><td></td><td>Is the inbox a favorite. Marking an inbox as a favorite is typically done in the dashboard for quick access or filtering</td></tr><tr><td><code>expiresIn</code></td><td>No</td><td><code>integer:int64</code></td><td></td><td>Number of milliseconds that inbox should exist for</td></tr><tr><td><code>allowTeamAccess</code></td><td>No</td><td><code>boolean</code></td><td></td><td>DEPRECATED (team access is always true). Grant team access to this inbox and the emails that belong to it for team members of your organization.</td></tr><tr><td><code>inboxType</code></td><td>No</td><td><code>enum: HTTP_INBOX | SMTP_INBOX</code></td><td></td><td>Type of inbox. HTTP inboxes are faster and better for most cases. SMTP inboxes are more suited for public facing inbound messages (but cannot send).</td></tr><tr><td><code>virtualInbox</code></td><td>No</td><td><code>boolean</code></td><td></td><td>Virtual inbox prevents any outbound emails from being sent. It creates sent email records but will never send real emails to recipients. Great for testing and faking email sending.</td></tr><tr><td><code>useShortAddress</code></td><td>No</td><td><code>boolean</code></td><td></td><td>Use a shorter email address under 31 characters</td></tr><tr><td><code>prefix</code></td><td>No</td><td><code>string</code></td><td></td><td>Prefix to add before the email address for easier labelling or identification.</td></tr></tbody>
</table>
</div>
</details>

Use the options-based create endpoint when you need custom addresses, custom domains, expiration, virtual inboxes, tags, or SMTP inbox behavior.

[API endpoint: `createInboxWithOptions`](/docs/api/#createInboxWithOptions)

## Fetching inboxes

![email api](/assets/inbox-emails.png)

You can list and fetch inboxes using the API.

### Listing inboxes

Inbox results are paginated. Pass a starting index and page size to paginate results.

```typescript
const mailslurp = new MailSlurp(config);

// get paginated inboxes
const [index, size] = [0, 20];
const pageInboxes = await mailslurp.getAllInboxes(0, 20);

expect(pageInboxes.size).toEqual(size);
expect(pageInboxes.number).toEqual(index);
```

### Get an inbox by ID

Inboxes can be fetched using their ID.

```typescript
const mailslurp = new MailSlurp(config);
const { id: inboxId } = await mailslurp.createInbox();
const inbox = await mailslurp.getInbox(inboxId);
expect(inbox.id).toEqual(inboxId);
```

### Delete an inbox

You can delete inboxes using the ID.

```typescript
await mailslurp.inboxController.deleteInbox({
  inboxId: inbox.id,
});
```

### Fetch emails in an inbox

Emails can be fetched for an inbox.

```typescript
const emails = await mailslurp.inboxController.getEmails({
    inboxId: inbox.id,
    unreadOnly: true,
});
expect(emails.length).toBeDefined();
```

Use the paginated inbox email endpoint when you need stable listing, sorting, and connector synchronization controls.

[API endpoint: `getInboxEmailsPaginated`](/docs/api/#getInboxEmailsPaginated)

<section data-component="DocsExamplesList" class="docs-related-examples" data-example-count="3">
<p class="docs-related-examples-title">Inbox workflow examples</p>
<p class="docs-related-examples-description">These repositories show inbox creation, browser tests, SMTP access, and received-email assertions.</p>
<div class="docs-card-grid docs-examples-list">
<a class="docs-card docs-example-card" href="https://www.github.com/mailslurp/examples/tree/master/playwright-email-testing" target="_blank" rel="noopener noreferrer"><span class="docs-card-title">Playwright Email Testing</span><span class="docs-card-description">playwright example repository: <code>playwright-email-testing</code></span></a>
<a class="docs-card docs-example-card" href="https://www.github.com/mailslurp/examples/tree/master/javascript-cypress-mailslurp-plugin" target="_blank" rel="noopener noreferrer"><span class="docs-card-title">Javascript Cypress Mailslurp Plugin</span><span class="docs-card-description">javascript example repository: <code>javascript-cypress-mailslurp-plugin</code></span></a>
<a class="docs-card docs-example-card" href="https://www.github.com/mailslurp/examples/tree/master/nodejs-nodemailer-smtp-example" target="_blank" rel="noopener noreferrer"><span class="docs-card-title">Nodejs Nodemailer Smtp Example</span><span class="docs-card-description">nodejs example repository: <code>nodejs-nodemailer-smtp-example</code></span></a>
</div>
</section>

## Inbox automations

Inboxes are component of many MailSlurp features:

| Feature                              | Description                                       |
|--------------------------------------|---------------------------------------------------|
| [AI transform](/docs/ai/)                 | Transform emails and attachments into data        |
| [Webhooks](/docs/webhooks/)               | Trigger actions based on email events             |
| [External connections](/docs/connectors/) | Connect inboxes to external email accounts        |
| [Forwarding](/docs/forwarding/)           | Forward emails to other email addresses           |
| [Routing rules](/docs/routing-rulesets/)  | Block and allows emails based on content matching |
| [Alias proxy](/docs/alias-proxy/)         | Mask an inbox with a proxy email address          |
| [Auto reply](/docs/repliers/)             | Send replies to inbound emails                    |
| [Mail trap](/docs/virtual-inbox/)         | Capture outbound emails but do not send them      |
| [Custom domains](/docs/custom-domains/)   | Use custom email addresses with inboxes           |
| [IMAP/SMTP](/docs/imap-smtp/)             | Send and receive emails using IMAP and SMTP       |

We will cover more email methods on the [email page](/docs/emails/).