# Connect external mail tools: IMAP and SMTP (/core/imap-smtp) Related: [Receive email](/core/receive.md), [Send and reply](/core/send.md), [Manage conversations](/core/conversations.md), [Control who can email your agent](/core/inbound-control.md), [Webhooks](/advanced/webhooks.md) # Connect a mail tool to an AgentMail inbox over IMAP and SMTP Every AgentMail inbox is a standard mailbox, so any mail client, library, or warm-up platform that accepts custom mail-server credentials can read it over IMAP and send from it over SMTP. Use this path for tools that speak mail protocols instead of the AgentMail API. ## Do this Log in with the full inbox address as the username and an AgentMail API key as the password. This script prints unread mail from `INBOX` over IMAP, then sends one message over SMTP: ```python import email import imaplib import os import smtplib from email.message import EmailMessage inbox = "example@agentmail.to" api_key = os.environ["AGENTMAIL_API_KEY"] with imaplib.IMAP4_SSL("imap.agentmail.to", 993) as imap: imap.login(inbox, api_key) imap.select("INBOX", readonly=True) status, ids = imap.search(None, "UNSEEN") for msg_id in ids[0].split(): status, data = imap.fetch(msg_id, "(RFC822)") message = email.message_from_bytes(data[0][1]) print(message["From"], "|", message["Subject"]) msg = EmailMessage() msg["Subject"] = "Hello over SMTP" msg["From"] = inbox # must be the inbox you authenticated as msg["To"] = "you@example.com" msg.set_content("Sent through smtp.agentmail.to.") with smtplib.SMTP_SSL("smtp.agentmail.to", 465) as smtp: smtp.login(inbox, api_key) smtp.send_message(msg) ``` Configuring a settings form instead: pick the account type named custom, other, or generic IMAP/SMTP (not the Google or Microsoft sign-in buttons), enter the IMAP and SMTP values from Facts, match the security dropdown to the port (SSL/TLS for `465`, STARTTLS for `587`), and set the From address to the same inbox address as the username. ## Facts * IMAP host `imap.agentmail.to`, port `993`, SSL/TLS encryption from the first byte. * SMTP host `smtp.agentmail.to`, port `465` (SSL/TLS from the first byte) or port `587` (plain connection upgraded with STARTTLS before login). * Encryption is required on every connection. * Username for both protocols: the full inbox address including its domain, for example `example@agentmail.to`. * Password for both protocols: an AgentMail API key. * IMAP exposes five folders: `INBOX`, `Sent`, `Trash`, `Spam`, `Drafts`. * `INBOX` matches in any casing. `Sent`, `Trash`, `Spam`, and `Drafts` are exact names. * `Sent` holds every message the inbox sent, through the API or through SMTP. * IMAP returns complete raw messages, headers and body included, the same messages the API returns. * The `Message-ID` header on an IMAP message is the value the API calls `message_id`. Use it through the API to reply in the message's thread or download its attachments. * Opening a folder read-only keeps fetches from marking messages as seen. * SMTP limit: 50 recipients per message, counting To, Cc, and Bcc together. * SMTP limit: 10 MB per message, attachments included. * SMTP sessions time out after 30 minutes. Open a connection per batch instead of holding one long term. * The SMTP From address must be the inbox address you authenticated as. * A successful SMTP send returns `250 Message queued as` followed by the new message's id. That id is the message's `message_id` everywhere else in AgentMail. * A message sent over SMTP appears in the message list with the `sent` label and in the IMAP `Sent` folder. The recipient's copy normally arrives within a few seconds. * On the Free and Agent plans, mail from a shared `@agentmail.to` address carries a `Sent via AgentMail` footer. * Clients that support IMAP IDLE get new mail pushed as it arrives. The server and client negotiate this automatically. ## Not supported * Drafts cannot be created or managed over IMAP. The `Drafts` folder exists for client compatibility and stays empty. Create and manage drafts through the API. * SMTP cannot send from a From address other than the authenticated inbox. * The Google and Microsoft sign-in buttons in mail clients do not work for AgentMail addresses. They run OAuth flows for accounts at those providers. Pick the custom, other, or generic IMAP/SMTP account type. * Unencrypted connections are not accepted on any port. An unencrypted connection to port `465` stalls until it times out. * A tool connected over SMTP alone can send but does not see replies. Enter the IMAP settings too when it needs reply detection or warm-up activity. ## Errors | Error | Protocol | Cause | Fix | | -------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `[AUTHENTICATIONFAILED] Invalid credentials` | IMAP | Wrong login, usually a username missing its domain or a password that is not an API key. | Log in with the full inbox address and an AgentMail API key. | | `535 5.7.8 Authentication credentials invalid` | SMTP | Wrong login, same causes as the IMAP variant. | Log in with the full inbox address and an AgentMail API key. | | TLS handshake error such as `wrong version number` | TLS | The encryption mode does not match the port, usually SSL/TLS selected for port `587`, which expects STARTTLS. | Use STARTTLS on `587`. Use SSL/TLS on `993` and `465`. | | Connection times out or is refused | TCP | The network cannot reach the server, usually a firewall blocking outbound `993`, `465`, or `587`. An unencrypted connection to `465` stalls the same way. | Allow outbound traffic on the port, and encrypt from the first byte on `465`. | | `Mailbox not found` | IMAP | The folder name does not match one of the five folders, usually a casing mismatch such as `sent` instead of `Sent`. | Use `INBOX`, `Sent`, `Trash`, `Spam`, or `Drafts` exactly. | | Zero or stale messages | IMAP | The tool is reading a different folder or reusing an old session. | Point the tool at `INBOX`, then trigger its sync or reconnect the account. | | `550 5.1.8 Sender address rejected` | SMTP | The From address is not one this login can send as. | Set From to the inbox address you authenticated as. | | `452 4.5.3 Too many recipients` | SMTP | The message went past 50 recipients across To, Cc, and Bcc. | Keep each message at 50 recipients or fewer. | | `538 Error: Must issue a STARTTLS command first` | SMTP | The client tried to log in before encrypting on port `587`. | Turn on STARTTLS, or use port `465`. | ## Verify ```python import imaplib import os import smtplib inbox = "example@agentmail.to" api_key = os.environ["AGENTMAIL_API_KEY"] with imaplib.IMAP4_SSL("imap.agentmail.to", 993) as imap: imap.login(inbox, api_key) print("IMAP login ok") with smtplib.SMTP_SSL("smtp.agentmail.to", 465) as smtp: smtp.login(inbox, api_key) print("SMTP login ok") ``` Two ok lines confirm the hosts, ports, encryption modes, and credentials all work together. If a tool still fails after this passes, the problem is in the tool's form, so compare every field against Facts. ## Related * [/quickstart](/quickstart): create the API key used as the password. * [/advanced/webhooks](/advanced/webhooks): react to incoming mail in real time instead of polling IMAP. * [/advanced/deliverability](/advanced/deliverability): how receivers authenticate your mail and how to warm up a new sending domain.