IMAP & SMTP

Connect to AgentMail with standard email protocols

AgentMail supports standard IMAP and SMTP protocols, allowing you to connect using traditional email clients or integrate with existing systems that rely on these protocols.

What are IMAP and SMTP?

IMAP (Internet Message Access Protocol) and SMTP (Simple Mail Transfer Protocol) are the standard protocols that power email communication across the internet.

  • IMAP is used to read and manage emails. It allows email clients to sync with a mail server, keeping your messages organized across multiple devices. When you check your inbox in Outlook or Thunderbird, you’re using IMAP.

  • SMTP is used to send emails. When you hit “Send” on an email, SMTP handles delivering that message to the recipient’s mail server.

Why Use IMAP/SMTP with AgentMail?

  • Email Client Integration: Connect Outlook, Thunderbird, Apple Mail, or any IMAP/SMTP-compatible client to your AgentMail inbox
  • Programmatic Access: Send and receive emails using standard libraries (like Python’s imaplib or smtplib) in any programming language
  • Legacy System Integration: Bridge AgentMail with existing systems that only support IMAP/SMTP protocols
  • Familiar Tooling: Use email tools you already know during development and testing

Finding Your Credentials

Before configuring IMAP or SMTP, you’ll need two pieces of information from the AgentMail Console:

1

Get Your Inbox ID (Username)

Navigate to Dashboard → Inboxes and find the Inbox ID column. Your inbox ID is your inbox’s email address (e.g., myinbox@agentmail.to). This will be your username for IMAP authentication.

2

Get Your API Key (Password)

Navigate to Dashboard → API Keys and create or copy an API key—this will be your password.

IMAP Configuration

Use IMAP to read emails from your AgentMail inbox.

SSL/TLS Required

SSL/TLS is required for all IMAP connections. Connections without SSL will be rejected. Make sure to enable SSL/TLS in your email client settings.

SettingValue
Hostimap.agentmail.to
Port993
UsernameYour inbox email (e.g., myinbox@agentmail.to)
PasswordYour API key
SSL/TLSRequired (must be enabled)
Folder Support

Currently, only the INBOX folder is accessible via IMAP. Other folders (Sent, Drafts, Trash) are not available through IMAP. Use the AgentMail API for full folder access.

Python IMAP Example

1import imaplib
2import os
3import email
4
5# Your credentials from AgentMail Console
6inbox_email = "myinbox@agentmail.to" # From Dashboard → Inboxes
7api_key = os.getenv("AGENTMAIL_API_KEY") # From Dashboard → API Keys
8
9# Connect with SSL (required)
10imap = imaplib.IMAP4_SSL("imap.agentmail.to", 993)
11
12try:
13 # Authenticate using inbox email as username
14 imap.login(inbox_email, api_key)
15
16 # Select INBOX (only supported folder)
17 imap.select("INBOX")
18
19 # Search for all messages
20 status, message_ids = imap.search(None, "ALL")
21
22 if status == "OK":
23 for msg_id in message_ids[0].split():
24 # Fetch message
25 status, msg_data = imap.fetch(msg_id, "(RFC822)")
26 if status == "OK":
27 email_body = msg_data[0][1]
28 message = email.message_from_bytes(email_body)
29 print(f"Subject: {message['subject']}")
30finally:
31 imap.logout()

TypeScript IMAP Example

1import Imap from "imap";
2
3// Your credentials from AgentMail Console
4const inboxEmail = "myinbox@agentmail.to"; // From Dashboard → Inboxes
5const apiKey = process.env.AGENTMAIL_API_KEY!; // From Dashboard → API Keys
6
7const imap = new Imap({
8 user: inboxEmail,
9 password: apiKey,
10 host: "imap.agentmail.to",
11 port: 993,
12 tls: true, // SSL required
13});
14
15imap.once("ready", () => {
16 imap.openBox("INBOX", false, (err, box) => {
17 if (err) throw err;
18 console.log(`${box.messages.total} messages in INBOX`);
19 imap.end();
20 });
21});
22
23imap.once("error", (err: Error) => {
24 console.error("IMAP error:", err.message);
25});
26
27imap.connect();

SMTP Configuration

Use SMTP to send emails from your AgentMail inbox.

SSL/TLS Required

SSL/TLS is required for all SMTP connections. Connections without SSL will be rejected. Make sure to enable SSL/TLS in your email client settings.

SettingValue
Hostsmtp.agentmail.to
Port465
Usernameagentmail
PasswordYour API key
SSL/TLSRequired (must be enabled)
From Address

The “From” address in your email should match the email address of your inbox (e.g., myinbox@agentmail.to). Using a different From address may result in delivery failures.

SMTP Limits

  • Max recipients: 50 per email
  • Max message size: 10MB
  • Session timeout: 30 minutes

Python SMTP Example

1import smtplib
2import os
3from email.mime.text import MIMEText
4from email.mime.multipart import MIMEMultipart
5
6# Your credentials from AgentMail Console
7inbox_email = "myinbox@agentmail.to" # From Dashboard → Inboxes
8api_key = os.getenv("AGENTMAIL_API_KEY") # From Dashboard → API Keys
9
10# Create message
11msg = MIMEMultipart()
12msg["Subject"] = "Hello from AgentMail"
13msg["From"] = inbox_email # Use your inbox email as the From address
14msg["To"] = "recipient@example.com"
15msg.attach(MIMEText("This is a test email sent via SMTP.", "plain"))
16
17# Connect with SSL (required) and send
18with smtplib.SMTP_SSL("smtp.agentmail.to", 465) as server:
19 server.login(inbox_email, api_key)
20 server.send_message(msg)
21 print("Email sent successfully!")

TypeScript SMTP Example

1import nodemailer from "nodemailer";
2
3// Your credentials from AgentMail Console
4const inboxEmail = "myinbox@agentmail.to"; // From Dashboard → Inboxes
5const apiKey = process.env.AGENTMAIL_API_KEY!; // From Dashboard → API Keys
6
7const transporter = nodemailer.createTransport({
8 host: "smtp.agentmail.to",
9 port: 465,
10 secure: true, // SSL required
11 auth: {
12 user: inboxEmail,
13 pass: apiKey,
14 },
15});
16
17async function sendEmail() {
18 const info = await transporter.sendMail({
19 from: inboxEmail, // Use your inbox email as the From address
20 to: "recipient@example.com",
21 subject: "Hello from AgentMail",
22 text: "This is a test email sent via SMTP.",
23 });
24 console.log("Email sent:", info.messageId);
25}
26
27sendEmail().catch(console.error);

Troubleshooting

ErrorCauseSolution
”Authentication failed”Invalid credentialsVerify your inbox email and API key from the console
”Connection refused”SSL not enabledEnable SSL/TLS in your client settings
”Connection timeout”Firewall blocking portsEnsure ports 993 (IMAP) and 465/587 (SMTP) are open
”Sender not authorized”Wrong From addressUse your inbox’s email address as the From address
”Folder not found”Non-INBOX folderOnly INBOX is supported; use the API for other folders

When to Use IMAP/SMTP vs API

Use CaseRecommendation
Email client integrationIMAP/SMTP
Simple programmatic sendingSMTP
Full inbox managementAPI
Real-time notificationsAPI (Webhooks)
Access to all foldersAPI
Bulk operationsAPI