Before you start

An Aquila account
The mailbox email address and username
IMAP host, port, and security mode
Optional SMTP host, port, and security mode for sending

Connect your custom IMAP mailbox in Aquila

Choose Other IMAP. Enter the incoming IMAP settings and optional outgoing SMTP settings from your host.

Open the dashboard and choose Add inbox.
Select the provider card when it is available, or use Other IMAP for custom settings.
Enter an inbox name, email address, and mailbox password or app password.

Screenshot slot: Add inbox dialogAquila interface capture

Use this slot for a screenshot of the Aquila provider picker or custom IMAP form.

Test and save the mailbox

Aquila tests the incoming IMAP connection and, when SMTP is enabled, the outgoing SMTP connection before saving credentials.

If SMTP uses a different credential, enable the separate SMTP password option.
A successful test confirms that the agent can reach the mailbox through Aquila.
Mailbox credentials are encrypted at rest and decrypted only for request-time access.

Screenshot slot: Connection testAquila interface capture

Use this slot for the Aquila Test connection step after the check animation succeeds.

Create an API key for your AI agent

Create a dedicated API key for each agent or workspace so access can be audited, scoped, and revoked independently.

Name the key after the agent or environment that will use it.
Select only the mailboxes this key should expose.
Optionally set an expiration date for temporary projects or contractor access.

Screenshot slot: API key dialogAquila interface capture

Use this slot for the Aquila API key configuration dialog with mailbox access selected.

Add Aquila as an MCP server in your AI agent

Use the Aquila MCP endpoint and the API key you created. The endpoint is http://localhost:8080/mcp.

Use an Authorization bearer token header with the API key.
Keep the API key secret. Aquila only shows it once after creation.
After connecting, ask the agent to list connected email addresses to verify access.

Screenshot slot: Agent MCP settingsAquila interface capture

Use this slot for the your AI agent MCP server configuration screen.

Reusable MCP configuration block

Use this block in every guide and replace the API key placeholder with the one-time key copied from Aquila.

{
  "mcpServers": {
    "aquila-email": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your aqla_ API key>"
      }
    }
  }
}

FAQ

Which security mode should I choose?

Use TLS/SSL for port 993 or 465, STARTTLS for port 143 or 587, and None only when your provider explicitly requires it.

Can read-only agents skip SMTP?

Yes. Disable SMTP if the agent only needs to search and read emails.

How to connect AI agents to custom IMAP