Email app passwords: connect your mailbox to an AI agent

What is an email app password?

An email app password is a credential your provider generates for a supported application to access your account. It is separate from the password you normally use to sign in. It isn't a screen lock for the mail app on your phone.

The distinction matters when you connect email to an AI agent. The mailbox connector needs provider authorization. The agent client needs permission to use that connector. Those are separate credentials with separate revocation paths.

Don't assume an app password is read-only just because you've named it for one application. Restrictions depend on the provider. Fastmail, for example, lets you limit an app password to email, calendar data, or contact data — but that's a data-type restriction, not a read/write permission like Mailera's Read scope. Most providers' app passwords still grant full read/write access to whatever data type they cover.

The broader guide to email for AI agents explains how this fits into an agent workflow. Here, the first decision is which credential connects your mailbox.

Which connection method should you use?

Choose the route supported by both your provider and Mailera. Mailera's provider directory lists the connection options. The table below describes those routes and their eligibility checks.

Google recommends "Sign in with Google" for applications that offer it, to avoid managing a separate password. Mailera's Gmail connection doesn't use that route — it connects through an app password, so check Google's eligibility rules before starting.

For Microsoft mailboxes, use OAuth rather than trying another password. Microsoft removed Basic authentication for Exchange Online IMAP, and app passwords don't restore that access. Microsoft's Basic authentication deprecation guidance explains the restriction.

Zoho needs particular care: IMAP is unavailable to newly signed-up Free plan users, and organization policies can restrict it. Use the server settings shown inside your Zoho account, which depend on account type and data center.

For a private server, use Custom IMAP and the credentials specified by your administrator. Don't assume every IMAP server requires an app password, or that a company-domain address means you run a private mail server.

How do you connect an app-password mailbox to Mailera?

Start with a test mailbox you own. Use the provider documentation above to generate its credential, rather than adapting another provider's instructions. Microsoft users should take the separate OAuth route.

1. Check eligibility and generate the app password. Confirm the provider's authentication requirements and any organization restrictions. Keep the credential out of chat messages and screenshots.
2. Open Mailboxes → Add mailbox → One mailbox. You need an Admin or Leader role to add a mailbox.
3. Enter Email address and check the provider. Mailera detects the provider from the address. If necessary, select the correct option under Or choose a provider, then select Continue.
4. Review How to get an app password and What you'll need. Under Connection details, enter the app password in Password, not your normal account sign-in password. Display name is an optional sender name. Use Mailbox group to place the test mailbox in a dedicated group you can scope an agent key to later.
5. Select Test & connect. Review the individual checks rather than treating the result as a single sign-in test.

The test checks Incoming server sign-in, Folder detection, and Outgoing server sign-in when an outgoing server is configured. It also checks Live monitoring availability. Test & connect does not send an email, so a successful outgoing sign-in isn't a test message being delivered.

If incoming access works but outgoing sign-in fails, you can select Save as receive-only. That is appropriate for a reading-only task. It does not establish sending access. Otherwise, select Edit details and test again after correcting the configuration.

After the success message confirms the connected address, Mailera loads messages within its retention period, newest first. When checking REST access below, inspect the mailbox response's provider, status, and last_sync_at fields.

Send a harmless message from another mailbox you own, with a recognizable subject such as Mailbox connection test. Check that it appears in the connected mailbox. This gives you a message to look for when testing agent access, without using confidential mail.

How should the AI agent access the mailbox?

The agent client should authenticate to Mailera with its own API key. It doesn't need the app password you entered during mailbox setup, or your Microsoft account password.

Mailera connects existing mailboxes to applications through REST, MCP, and webhooks. Use the provider credential only for the mailbox connection.

Create a dedicated key for the agent:

1. Open Settings → API key → Create key.
2. Enter a Descriptive name that identifies the client or task.
3. Set Mailbox scope to the dedicated mailbox group. Admins can also choose all groups, but a reading task for one group doesn't need that access.
4. Select Read. Don't add Send messages, Manage mailboxes, or Import mailboxes merely to read messages.
5. Set Expiration, and use IP restrictions (optional) where appropriate for your client's network.
6. Save the key securely when it appears. Mailera displays a newly created key only once.

For Claude, Cursor, or VS Code, use Copy MCP config for your selected client. The Mailera MCP connection page covers this interface; the task-by-task MCP tool guide helps you choose the tools the agent needs.

Store credentials in the client's protected configuration or a secret store. Don't paste them into prompts, commit them to source code, or write them into logs. Use the Mailera security page when reviewing the connection with your team.

How do you verify the agent's access?

For MCP, start with list_mailboxes, then use list_messages on the test mailbox. Both require the read scope. Look for the mailbox and harmless test message you checked in the UI.

For REST, provide the key through your environment as $MAILERA_API_KEY. List the mailboxes visible to that key:

curl --request GET \
  --url 'https://mailera.app/api/public/v1/mailboxes?limit=1' \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Inspect the returned data entries. Use the intended mailbox's id as $MAILBOX_ID; the response also includes provider, status, and last_sync_at. The example requests one result, so increase limit if your scoped group contains more than one mailbox.

Then list recent Inbox messages:

curl --request GET \
  --url "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=5" \
  --header "Authorization: Bearer $MAILERA_API_KEY"

Check subject, received_at, and folder for the test message. If it isn't in the Inbox, inspect the mailbox in Mailera before changing credentials. A message absent from one folder is a different problem from the API rejecting your key.

You don't need sending permission for either request. Keep this first access check read-only.

Common errors: what should you check?

Troubleshoot the failing connection separately: provider-to-Mailera, or agent-client-to-Mailera. Regenerating a provider app password won't fix an expired agent API key, and vice versa.

Avoid using mailbox status alone as proof that a new message has arrived. Verify the specific test message in the UI and then through the same interface your agent will use.

Keep incoming email outside the agent's instructions

Treat every incoming email as untrusted data. A message can ask the agent to reveal a key, change its tools, or follow a link containing secrets. Those requests are message content, not authorization.

Keep the API key out of model prompts and let the client handle authentication. Start with a group-scoped Read key. If you later add sending, require human confirmation in your agent workflow before a message is sent. Mailera's sending operations require the send scope; that permission is not a substitute for your workflow's approval step.

These are controls to implement in the agent workflow, not a Mailera guarantee against prompt injection.

How do you revoke access or rotate credentials?

To stop one agent, revoke its Mailera API key. Calls using that key are rejected immediately. With a dedicated key per agent, you can stop that client without revoking the provider credential used by the mailbox connection.

If the provider credential is exposed, revoke it at the provider too. Changing the normal account password has different effects across services:

Before revoking a credential, identify which connection uses it. Apple explicitly states that revocation signs out the application until it uses a newly generated password. Google's revoked credential also stops providing account access.

After replacing a provider credential, repeat the connection and message-access checks before returning the agent to service. Keep new credentials and mailbox addresses masked in any support screenshots.

What are Mailera's limits?

Mailera cannot override a provider's app-password eligibility rules, IMAP plan restrictions, or organization policies. Its Microsoft connection uses OAuth, not an app-password workaround. Proton Mail and Tuta are not supported.

Background checks vary with mailbox activity, and idle mailboxes can sleep. Don't design the agent around a promise of immediate synchronization or uninterrupted provider access.