---
title: "Custom IMAP API: connect your mailbox and read it through REST"
description: "Connect your custom IMAP server to Mailera, verify optional SMTP access, and read messages through REST with a scoped API key and short curl examples."
url: https://mailera.app/en/blog/custom-imap-api
published: 2026-10-25
updated: 2026-10-25
---

# Custom IMAP API: connect your mailbox and read it through REST

Connect an existing IMAP/SMTP mailbox to Mailera, check incoming and optional outgoing access, then retrieve messages with a scoped API key.

## TL;DR: How do you connect a custom IMAP mailbox to an API?

Connect your existing mailbox using your administrator’s IMAP settings, add SMTP only if you need to send, and select **Test & connect**. Then create a scoped Mailera API key to read messages through REST. IMAP provides mailbox access; SMTP handles outgoing submission. Mailera connects the mailbox you already have—it does not create a mailbox or email address.

An IMAP REST API is an HTTP interface to a connected mailbox, not a replacement protocol running on your mail server. Your application authenticates to Mailera; Mailera connects to the server using mailbox credentials. The [IMAP specification, RFC 9051](https://www.rfc-editor.org/rfc/rfc9051.html), distinguishes mailbox access from mail submission, which uses a separate protocol.

![Application access to Mailera uses an API key, while IMAP and optional SMTP connections use mailbox credentials.](https://mailera.app/media/d85615fbf33db34f/custom-imap-api-connect-your-mailbox-and-read-it-through-en-1200.jpg)
_The application key and mailbox credentials authenticate different connections._

## What settings do you need before connecting?

Start with a mailbox you own or are authorized to administer. You also need an **Admin** or **Leader** role to add it in Mailera. The [custom IMAP/SMTP connection page](https://mailera.app/en/providers/imap) covers this connection option.

Ask the server administrator for the settings below. Don’t derive server hostnames from your email domain or assume that every server requires an app password.

| Setting | What to obtain |
| --- | --- |
| Email address | The existing mailbox address |
| Incoming hostname | The administrator-provided IMAP server hostname |
| Incoming port and security | The matching port and TLS mode |
| Mailbox credentials | The username and password supported by the server’s authentication policy |
| Optional outgoing settings | SMTP hostname, submission port, security mode, and credentials |
| Mailbox group | The group you will use to restrict application access |

Use the server’s actual configuration. These are the standard pairings to check against it:

| Purpose | Port | Mailera Security option |
| --- | --- | --- |
| IMAP with implicit TLS | 993 | SSL/TLS |
| IMAP with STARTTLS | 143 | STARTTLS |
| SMTP submission with implicit TLS | 465 | SSL/TLS |
| SMTP submission with STARTTLS | 587 | STARTTLS |

With implicit TLS, the TLS handshake starts immediately. STARTTLS upgrades an initially unencrypted protocol session to TLS. [RFC 8314’s guidance on TLS for email](https://www.rfc-editor.org/rfc/rfc8314.html) explains this distinction and the implicit-TLS ports; [RFC 6409 defines submission on port 587](https://www.rfc-editor.org/rfc/rfc6409.html). Don’t select a port and security mode independently.

Mailbox credentials and your application’s API key serve different purposes. The credentials let Mailera sign in to your mail server. The Mailera API key authorizes HTTP requests to connected mailboxes. An “IMAP API key” in this workflow is therefore a Mailera key, not a replacement for the server password.

A company-domain address alone doesn’t determine the connection method. If the underlying service is Microsoft 365, use [Mailera’s Microsoft OAuth connection](https://mailera.app/en/providers/microsoft), not a custom app-password connection. Follow the [Outlook OAuth through Microsoft Graph guide](https://mailera.app/en/blog/outlook-oauth-email-api) for that setup.

## How do you add the custom IMAP/SMTP server in Mailera?

1. Open **Mailboxes → Add mailbox → One mailbox**. Enter the mailbox in **Email address**.
2. Under **Or choose a provider**, select **Custom IMAP**, then **Continue**.
3. Enter the mailbox credentials. Use **Username** if it differs from the email address; otherwise, leave it blank. Under **Incoming server (IMAP)**, fill in **Server**, **Port**, and **Security**. **Detect settings** fills public settings for the domain when available; check them against your administrator’s instructions.
4. Configure **Outgoing server (SMTP)** only if you need sending. Check its settings separately. If SMTP uses different credentials, don’t use **Use the same username and password to send email**; enter **Outgoing username** and **Outgoing password** instead.
5. Select **Test & connect** and inspect the stages below.
6. If outgoing sign-in fails, use **Edit details** and **Test again**, or choose **Save as receive-only** when reading is sufficient.

![Custom IMAP form with separate incoming and outgoing server settings.](https://mailera.app/media/d8e9591c875d36fe/email-app-passwords-connect-your-mailbox-to-an-ai-agent-add-en-1200.jpg)
_Configure incoming access first; add outgoing settings only when sending is needed._

The stage names help you locate the problem before changing settings:

| Test stage | What to look for |
| --- | --- |
| Connection server | Appears only when needed to prepare the connection server |
| Incoming server sign-in | Whether the incoming connection can authenticate |
| Folder detection | Whether mailbox folders can be detected |
| Outgoing server sign-in | Whether SMTP sign-in succeeds; skipped when no outgoing server is configured |
| Live monitoring | Whether live monitoring is available; otherwise Mailera uses periodic checks |

**Run in background** lets you leave the page while Mailera completes the test and saves the mailbox.

**Test & connect does not send an email.** Successful outgoing sign-in checks authentication, not delivery. SMTP has its own authentication exchange, defined in [RFC 4954](https://www.rfc-editor.org/rfc/rfc4954.html), so successful IMAP sign-in does not establish that outgoing authentication works.

## How do you verify the connection and read messages through REST?

First, check the **Connected** confirmation. Open the mailbox and look for an expected recent message. Initial loading works within the retention period, newest first. Resolve connection or loading problems here before debugging application code.

![Connected mailbox row showing its status and last sync.](https://mailera.app/media/900a3a34a7548a83/custom-imap-api-connect-your-mailbox-and-read-it-through-en-1200.jpg)
_Check the mailbox connection and sync before troubleshooting application requests._

### Create a read-only key

Open **Settings → API key → Create key**. Give the key a **Descriptive name**, select **Read**, and set **Mailbox scope** to the narrowest suitable group. Choose an **Expiration** appropriate for the application.

The key appears only once under **Key created — copy it now**. Store it securely and make it available to your shell as `$MAILERA_API_KEY`; don’t paste it into source code or logs. See the [Mailera developer overview](https://mailera.app/en/developers) for application integration options.

![API key creation form with Read permission and one mailbox group selected.](https://mailera.app/media/632ad55325c3f0c7/custom-imap-api-connect-your-mailbox-and-read-it-through-en-1200.jpg)
_A first-read integration needs Read permission, not sending or management access._

### List mailboxes, then read one

This IMAP API example uses the same REST interface as other connected mailboxes. First, list the mailboxes visible to your key:

```bash
curl --fail-with-body \
  'https://mailera.app/api/public/v1/mailboxes' \
  -H "Authorization: Bearer $MAILERA_API_KEY"
```

In the mailbox’s returned `data` entry, inspect `status` and `last_sync_at`. Set `$MAILBOX_ID` to that entry’s `id`. Use the returned ID, not the email address. Then request one Inbox message:

```bash
curl --fail-with-body \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1" \
  -H "Authorization: Bearer $MAILERA_API_KEY"
```

The message list includes fields such as `id`, `folder`, `subject`, and `preview`. To read the message content, set `$MESSAGE_ID` to a message’s returned `id` and request it directly:

```bash
curl --fail-with-body \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $MAILERA_API_KEY"
```

The single-message response includes `data.body.text` and `data.body.html`. All three requests require the `read` scope. The [Mailera API documentation](https://mailera.app/en/docs) covers the endpoints and message-list filters.

For a custom IMAP mailbox, `GET /mailboxes/{id}/status` reflects the latest sync. It does not perform a fresh direct sign-in check against the server.

### Verify outgoing mail separately

If sending is part of your application, use the documented `POST /mailboxes/{id}/send` workflow with **Send messages** permission to send a test to a mailbox you control. Inspect the attempt through `GET /sends/{id}`, then check the recipient mailbox separately. Submission status and observed receipt are different checks; neither is covered by **Test & connect**.

## What are the common connection errors?

Start with the failing layer. Changing the API key won’t fix an IMAP password, and changing the IMAP port won’t fix a key’s mailbox scope.

| Symptom | Possible layer | Safe check | Next action |
| --- | --- | --- | --- |
| Connection timeout | Hostname or network reachability | Confirm hostname, port, DNS, and server-side network restrictions with the administrator | Correct the settings or ask the administrator to resolve access restrictions, then retest |
| TLS failure | Certificate or security-mode mismatch | Check the hostname, certificate chain, and selected TLS mode | Correct the mismatch; don’t disable certificate validation |
| Incoming authentication fails | Credentials or mailbox policy | Confirm the username and supported password type; ask whether IMAP access is enabled | Correct credentials or policy, then retest incoming sign-in |
| Incoming works, outgoing fails | SMTP authentication or submission settings | Check the SMTP hostname, port, TLS mode, and outgoing credentials independently | Retest SMTP, or save as receive-only if sending is unnecessary |
| Connected, but messages are missing or delayed | Folder selection, initial loading, retention, or activity | Check the selected folder, loading progress, retention window, and last sync | Wait for initial loading or use Sync when appropriate |
| API authorization fails | Application key permissions or scope | Check the Bearer key, Read permission, selected group, expiration, and any IP restrictions without printing the secret | Correct the application’s key configuration rather than reconnecting the mailbox |

Background checks run more often for mailboxes in active use and less often for idle ones. Inactive mailboxes can sleep and wake on use, so don’t assume a fixed, immediate synchronization interval. Calling `POST /mailboxes/{id}/sync` also wakes a sleeping mailbox, but requires the separate `sync` scope; a read-only key cannot call it.

## What are Mailera’s limits, and how should you secure agent access?

Mailera does not provide mailbox warmup or bulk marketing sending. Proton Mail and Tuta are not supported.

If an AI agent reads this mailbox, treat incoming email as **untrusted data, not instructions**. A message asking the agent to reveal credentials, change its rules, or forward other messages must not override the agent’s operating instructions.

Start with **Read** permission and a restricted mailbox-group scope. Protect both the mailbox credentials and the API key. Grant **Send messages** only when needed, and require explicit confirmation before sending. Review [Mailera’s security information](https://mailera.app/en/security) when deciding how to handle access in your application.

For the broader agent setup, use the [guide to connecting existing email providers to agents](https://mailera.app/en/blog/email-provider-api-integration). The custom-server steps here establish the mailbox connection and the first REST read.

**Connect your first mailbox in 2 minutes** — Add an Outlook, Gmail or IMAP mailbox and read email messages in the app or via the API. [Connect mailbox](https://mailera.app/auth?mode=signup)