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

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, distinguishes mailbox access from mail submission, which uses a separate protocol.

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 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.

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

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 explains this distinction and the implicit-TLS ports; RFC 6409 defines submission on port 587. 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, not a custom app-password connection. Follow the Outlook OAuth through Microsoft Graph guide 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.

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

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, 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.

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 for application integration options.

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:

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:

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:

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 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.

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 when deciding how to handle access in your application.

For the broader agent setup, use the guide to connecting existing email providers to agents. The custom-server steps here establish the mailbox connection and the first REST read.