> ## Documentation Index
> Fetch the complete documentation index at: https://inbound.new/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect with IMAP

> Create a managed mailbox credential and read mail over IMAP

Connect an email client or application to Inbound using a managed **Mailbox + SMTP** credential. The same login email and generated password also work for [sending with SMTP](https://inbound.new/docs/mailboxes/connect-smtp.md).

## Connection settings

| Setting | Value |
| - | - |
| Host | `imap.inboundemail.com` |
| Port | `993` |
| Security | Implicit TLS (SSL/TLS), TLS 1.2 or later |
| Username | The credential's **Login email** |
| Password | The credential's generated password |
| Authentication | Normal password (`LOGIN` or `AUTHENTICATE PLAIN`) |

Port `143` and IMAP `STARTTLS` are not offered. Keep certificate verification enabled. Ordinary account API keys and **SMTP only** credentials cannot authenticate to IMAP.

> [!NOTE]
>
> Mail you send with a **Read & write** credential, over SMTP or the HTTP API, is saved to its `Sent` folder automatically. Deleting a received message in IMAP removes it from this credential's folders only; it stays in your account and the dashboard. Review [IMAP behavior and limits](https://inbound.new/docs/mailboxes/imap-behavior.md) before configuring a traditional email client.

## Create a mailbox credential

**1. Open Mailboxes & SMTP**

Add and verify a domain in [domain settings](https://inbound.new/emails), including its receiving MX records if you want incoming mail. Then open the [Mailboxes & SMTP dashboard](https://inbound.new/mailboxes) and select **Create credential**.

**2. Choose the credential and access**

Select **Mailbox + SMTP** under **Credential type**. Enter a descriptive **Name** and a **Login email** on an exact domain you own and have verified. The login email is your authentication username; it does not have to match the receiving or sending address.

Under **Access**, choose **Read only** to read mail over IMAP without changing the mailbox or sending, or **Read & write** to also send through SMTP, save messages in `Sent` or `Drafts`, change flags, and modify supported mailboxes. Read-only credentials cannot send mail. Scope-specific folders are always read-only.

**3. Set the sender policy**

Select **Exact identity** to restrict sending to one **Exact From address** covered by a scope. The optional dashboard **Display name** does not set the name recipients see; provide that name in your email client's From header instead.

Alternatively, select **Any scoped domain** to permit any sender address on each exact domain represented by your scopes. Subdomains are not included.

> [!WARNING]
>
> An address scope only limits which mail is received. With **Any scoped domain**, a scope for `support@example.com` still permits sending from `billing@example.com`, `admin@example.com`, or any other address at `example.com`. Choose **Exact identity** to restrict sending to one address.

**4. Add verified domain or address scopes**

Under **Mail access & sending scopes**, choose **Domain** for an entire verified domain or **Address** for one exact address. For an address scope, enter the local part without `@`, then choose the verified domain.

Select **Add** for each scope. At least one scope is required, and scopes determine which received messages are visible through IMAP.

**5. Create the credential and save its password**

Select **Create credential**. The confirmation dialog displays the **Username**, generated **Password**, and the IMAP and SMTP connection settings.

Copy the password into a password manager or secret manager before selecting **I saved the password**.

> [!WARNING]
>
> The generated password is a mail-scoped API key and is shown only once. Anyone with it can send mail within its sender policy, including through the HTTP email-sending endpoint. If it is lost or exposed, rotate it immediately and update every client.

## Set up an email client

Every client needs the same values. Use the address you send from as the account's email address, and the credential's **Login email** as the user name for both servers. They can be different addresses.

| Field | Incoming (IMAP) | Outgoing (SMTP) |
| - | - | - |
| Server | `imap.inboundemail.com` | `smtp.inboundemail.com` |
| Port | `993` | `465`, or `587` |
| Security | SSL/TLS | SSL/TLS on `465`, STARTTLS on `587` |
| Authentication | Normal password | Normal password |
| User name | Login email | Login email |
| Password | Generated password | Generated password |

Automatic setup doesn't find these servers, so enter them manually. The client sees the `Sent`, `Drafts`, `Trash`, `Junk` and `Archive` folders through their special-use attributes and uses them automatically.

> [tab] Apple Mail
>
> 1. Open **Mail** and choose **Mail** > **Add Account**, select **Other Mail Account**, then **Continue**.
> 2. Enter your name, the address you send from and the generated password, then select **Sign In**.
> 3. When Mail says it can't verify the account, set **Account Type** to **IMAP**, **Incoming Mail Server** to `imap.inboundemail.com`, **Outgoing Mail Server** to `smtp.inboundemail.com`, and **User Name** to the login email. Select **Sign In**.
> 4. If Mail still can't connect, open **Mail** > **Settings** > **Accounts** > **Server Settings**. For both servers, clear **Automatically manage connection settings**, then set the port (`993` incoming, `465` or `587` outgoing), select **Use TLS/SSL**, and set **Authentication** to **Password**.

> [tab] iPhone and iPad
>
> 1. Open **Settings** > **Apps** > **Mail** > **Mail Accounts** > **Add Account** > **Other** > **Add Mail Account**. On iOS 17 and earlier, start from **Settings** > **Mail** > **Accounts**.
> 2. Enter your name, the address you send from and the generated password, then tap **Next**.
> 3. Select **IMAP**. Under **Incoming Mail Server** and **Outgoing Mail Server**, enter the host names above and the login email and password. The outgoing user name and password are marked optional, but they are required. Tap **Next**, then **Save**.
> 4. If the connection fails, open the account's **Advanced** settings and check that **Use SSL** is on with port `993`. Under **Outgoing Mail Server** > **SMTP**, select the server, turn on **Use SSL**, set **Authentication** to **Password** and **Server Port** to `465`.

> [tab] Thunderbird
>
> 1. Open **Account Settings** > **Account Actions** > **Add Mail Account**.
> 2. Enter your name, the address you send from and the generated password, then select **Configure manually**.
> 3. Under **Incoming Server**, set **Protocol** to **IMAP**, **Hostname** to `imap.inboundemail.com`, **Port** to `993`, **Connection security** to **SSL/TLS**, **Authentication method** to **Normal password**, and **Username** to the login email.
> 4. Under **Outgoing Server**, set **Hostname** to `smtp.inboundemail.com`, **Port** to `465` with **SSL/TLS** (or `587` with **STARTTLS**), **Authentication method** to **Normal password**, and **Username** to the login email.
> 5. Select **Re-test**, then **Done**.

> [tab] Outlook
>
> **New Outlook for Windows and Outlook for Mac**
>
> 1. Open **Settings** > **Accounts** and choose to add an account. Enter the address you send from.
> 2. When Outlook asks for the provider, choose **IMAP** and open the advanced or manual settings.
> 3. Enter the login email as the IMAP and SMTP user name, the generated password, `imap.inboundemail.com` port `993` with **SSL/TLS**, and `smtp.inboundemail.com` port `465` with **SSL/TLS** or `587` with **STARTTLS**.
>
> **Classic Outlook for Windows**
>
> 1. Select **File** > **Add Account**, enter the address you send from, open **Advanced options**, select **Let me set up my account manually**, then choose **IMAP**.
> 2. Set **Incoming mail** to `imap.inboundemail.com`, port `993`, encryption **SSL/TLS**, and **Outgoing mail** to `smtp.inboundemail.com`, port `587` with **STARTTLS** or `465` with **SSL/TLS**. Leave **Require logon using Secure Password Authentication (SPA)** cleared.
> 3. Enter the generated password. If Outlook signs in with the wrong user name, open the account's server settings and set the user name to the login email.

Inbound saves a copy of each message you send to `Sent`. Clients that also save their own copy don't create a duplicate, because copies with the same `Message-ID` are merged. A client copy larger than 1 MiB is rejected by `APPEND`, but the automatic copy is still saved.

## Connect from your application

Store your managed credential as `INBOUND_MAILBOX_LOGIN` and `INBOUND_MAILBOX_PASSWORD` in your application's secret manager or environment. Both examples open `INBOX` read-only and inspect message headers without changing mailbox state.

For the TypeScript example, install ImapFlow:

```bash theme={null}
bun add imapflow
```

```typescript ImapFlow theme={null}
import { ImapFlow } from "imapflow";

const login = process.env.INBOUND_MAILBOX_LOGIN;
const password = process.env.INBOUND_MAILBOX_PASSWORD;

if (!login || !password) {
  throw new Error("Set INBOUND_MAILBOX_LOGIN and INBOUND_MAILBOX_PASSWORD");
}

const client = new ImapFlow({
  host: "imap.inboundemail.com",
  port: 993,
  secure: true,
  auth: { user: login, pass: password },
});

await client.connect();

try {
  const lock = await client.getMailboxLock("INBOX", { readOnly: true });

  try {
    const totalMessages = client.mailbox ? client.mailbox.exists : 0;

    if (totalMessages === 0) {
      console.log("INBOX is empty");
    } else {
      const firstMessage = Math.max(1, totalMessages - 9);
      const range = `${firstMessage}:${totalMessages}`;

      for await (const message of client.fetch(range, { envelope: true })) {
        console.log({
          uid: message.uid,
          from: message.envelope?.from,
          subject: message.envelope?.subject,
        });
      }
    }
  } finally {
    lock.release();
  }
} finally {
  await client.logout();
}
```

```python Python theme={null}
import imaplib
import os
import ssl
from email import policy
from email.parser import BytesParser

login = os.environ["INBOUND_MAILBOX_LOGIN"]
password = os.environ["INBOUND_MAILBOX_PASSWORD"]
context = ssl.create_default_context()

with imaplib.IMAP4_SSL(
    "imap.inboundemail.com", 993, ssl_context=context
) as client:
    client.login(login, password)

    status, _ = client.select("INBOX", readonly=True)
    if status != "OK":
        raise RuntimeError("Could not open INBOX")

    status, message_ids = client.search(None, "ALL")
    if status != "OK":
        raise RuntimeError("Could not search INBOX")

    for message_id in message_ids[0].split()[-10:]:
        status, parts = client.fetch(
            message_id,
            "(BODY.PEEK[HEADER.FIELDS (FROM SUBJECT DATE)])",
        )
        if status != "OK":
            continue

        for part in parts:
            if isinstance(part, tuple) and isinstance(part[1], bytes):
                headers = BytesParser(policy=policy.default).parsebytes(part[1])
                print({
                    "from": str(headers.get("From", "")),
                    "subject": str(headers.get("Subject", "")),
                    "date": str(headers.get("Date", "")),
                })
```

> [!NOTE]
>
> `BODY.PEEK` reads the requested headers without marking a message as seen. Opening `INBOX` in read-only mode also works with both **Read only** and **Read & write** credentials.

## Troubleshooting

### Authentication fails

IMAP answers every refused login with the same `NO [AUTHENTICATIONFAILED]`, so check each of these:

* **Wrong credential.** Use the **Login email** as the user name, even when you send from a different address, and the generated `mail_` (or legacy `imap_`) password, not an account API key or your dashboard password. A rotated password stops working at once.
* **Credential type.** **SMTP only** credentials can't log in to IMAP.
* **Disabled credential.** Re-enable it in the dashboard.
* **Protocol turned off.** The credential's `protocols.imap` setting is off. See [Access and Limits](https://inbound.new/docs/mailboxes/access-and-limits.md#protocols).
* **IP address not allowed.** The credential has an `allowedIps` list that doesn't include your client's public address. See [allowed IP addresses](https://inbound.new/docs/mailboxes/access-and-limits.md#allowed-ip-addresses).
* **Domain no longer verified.** The login email's domain, or every scope domain, lost its verified status in [domain settings](https://inbound.new/emails).
* **Too many failures.** After 10 failed logins for the same login email from the same IP address, or 50 from the same IP address, within 15 minutes, every attempt is refused until the window ends, even with the correct password.

A `NO [TEMPFAIL]` response means the login couldn't be checked right now, because the authentication service was unavailable or rate limited. Retry later with backoff.

### The connection closes right away

The server allows 20 simultaneous connections per client IP address and drops any connection above that without a reply. Close unused sessions or lower your client's connection count. A connection that hasn't logged in within 30 seconds receives `* BYE Authentication timeout, closing connection`. See [connection limits and timeouts](https://inbound.new/docs/mailboxes/imap-behavior.md#connection-limits-and-timeouts).

### The connection closes after a settings change

Changing the credential's password, scopes, access, sender policy, enabled state, `protocols`, `allowedIps` or `selfService` ends its open IMAP sessions with `* BYE Mailbox credentials or scopes changed`. Reconnect with the current settings.

### The inbox is empty or a message is missing

* Check that the receiving domain is verified and its receiving MX records are configured in [domain settings](https://inbound.new/emails).
* Confirm the message's recipient matches one of the credential's domain or address scopes. The login email alone doesn't grant access to other mail.
* Look in `Junk`. The [junk filter](https://inbound.new/docs/mailboxes/junk-filter.md) puts mail it marks as junk there instead of in `INBOX`. Move a message back to `INBOX` to mark it as not junk for this credential.
* Check the credential's [filters](https://inbound.new/docs/mailboxes/filters.md), which can move new mail to other folders.
* On a mailbox with a lot of existing mail, each sync adds at most 500 messages, newest first, so older mail appears over the next few refreshes.

### Saving a message fails

`APPEND` rejects messages over 1 MiB with `NO [TOOBIG]`, and returns `NO [OVERQUOTA]` when the account's appended storage (250 MiB or 5,000 messages) or the credential's [storage quota](https://inbound.new/docs/mailboxes/access-and-limits.md#storage-quota) is full. Delete drafts or saved copies you no longer need, or raise the quota. See [message and storage limits](https://inbound.new/docs/mailboxes/imap-behavior.md#message-and-storage-limits).

### Sending fails

Sending uses SMTP. A `451` reply that says the daily sending limit was reached means the credential's [daily send limit](https://inbound.new/docs/mailboxes/access-and-limits.md#daily-send-limit) is used up until 00:00 UTC. For other codes, see [Send with SMTP](https://inbound.new/docs/mailboxes/connect-smtp.md#reply-codes).

### TLS or certificate validation fails

Use port `993` with implicit TLS (often labeled SSL/TLS), not STARTTLS, and make sure the client supports TLS 1.2 or later. Keep hostname and certificate validation enabled. Test the TLS handshake without providing a username or password:

```bash theme={null}
openssl s_client -connect imap.inboundemail.com:993 \
  -servername imap.inboundemail.com \
  -verify_hostname imap.inboundemail.com \
  -verify_return_error
```

After the handshake, type `a CAPABILITY` to see the advertised capabilities and `b LOGOUT` to close the connection.

### A domain is missing from the scope selector

[Add and verify the domain](https://inbound.new/emails) before creating or editing a credential, and use an exact owned, verified domain for the login email. Select **Add** after configuring each scope.

Learn more about [scopes and permissions](https://inbound.new/docs/mailboxes/scopes-and-permissions.md), [managing credentials](https://inbound.new/docs/mailboxes/manage-credentials.md), and [IMAP behavior](https://inbound.new/docs/mailboxes/imap-behavior.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.