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:

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.

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.

Setting	Value
Host	`imap.agentmail.to`
Port	`993`
Username	Your inbox email (e.g., `myinbox@agentmail.to`)
Password	Your API key
SSL/TLS	Required (must be enabled)

Folder Support

IMAP exposes the following folders: INBOX, Sent, Trash, and Spam. A Drafts folder is also listed for client compatibility but always appears empty — use the AgentMail API to create and manage drafts.

Real-time updates with IDLE

The IMAP server supports the IDLE extension (RFC 2177), so modern clients (Thunderbird, Outlook, Apple Mail) receive new messages push-style without polling. Clients negotiate IDLE automatically when supported — no extra configuration needed.

Python IMAP Example

1 import imaplib
2 import os
3 import email
4 
5 # Your credentials from AgentMail Console
6 inbox_email = "myinbox@agentmail.to"  # From Dashboard → Inboxes
7 api_key = os.getenv("AGENTMAIL_API_KEY")  # From Dashboard → API Keys
8 
9 # Connect with SSL (required)
10 imap = imaplib.IMAP4_SSL("imap.agentmail.to", 993)
11 
12 try:
13     # Authenticate using inbox email as username
14     imap.login(inbox_email, api_key)
15 
16     # Select a folder (INBOX, Sent, Trash, or Spam)
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']}")
30 finally:
31     imap.logout()

TypeScript IMAP Example

1 import Imap from "imap";
2 
3 // Your credentials from AgentMail Console
4 const inboxEmail = "myinbox@agentmail.to"; // From Dashboard → Inboxes
5 const apiKey = process.env.AGENTMAIL_API_KEY!; // From Dashboard → API Keys
6 
7 const imap = new Imap({
8   user: inboxEmail,
9   password: apiKey,
10   host: "imap.agentmail.to",
11   port: 993,
12   tls: true, // SSL required
13 });
14 
15 imap.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 
23 imap.once("error", (err: Error) => {
24   console.error("IMAP error:", err.message);
25 });
26 
27 imap.connect();

SMTP Configuration

Use SMTP to send emails from your AgentMail inbox.

Encryption Required

Encryption is required for all SMTP connections. Connect using port 465 with implicit TLS (SSL on connect) or port 587 with STARTTLS (upgrade in-band). On port 587, attempting to authenticate before issuing STARTTLS is rejected with a 538 error.

Setting	Value
Host	`smtp.agentmail.to`
Port	`465` (implicit TLS) or `587` (STARTTLS)
Username	Your inbox email (e.g., `myinbox@agentmail.to`)
Password	Your API key
Encryption	Port `465`: SSL/TLS on connect · Port `587`: STARTTLS

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

1 import smtplib
2 import os
3 from email.mime.text import MIMEText
4 from email.mime.multipart import MIMEMultipart
5 
6 # Your credentials from AgentMail Console
7 inbox_email = "myinbox@agentmail.to"  # From Dashboard → Inboxes
8 api_key = os.getenv("AGENTMAIL_API_KEY")  # From Dashboard → API Keys
9 
10 # Create message
11 msg = MIMEMultipart()
12 msg["Subject"] = "Hello from AgentMail"
13 msg["From"] = inbox_email  # Use your inbox email as the From address
14 msg["To"] = "recipient@example.com"
15 msg.attach(MIMEText("This is a test email sent via SMTP.", "plain"))
16 
17 # Connect with implicit TLS on port 465 and send
18 with 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!")
22 
23 # Alternatively, use STARTTLS on port 587:
24 #   with smtplib.SMTP("smtp.agentmail.to", 587) as server:
25 #       server.starttls()
26 #       server.login(inbox_email, api_key)
27 #       server.send_message(msg)

TypeScript SMTP Example

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

Troubleshooting

Error	Cause	Solution
”Authentication failed”	Invalid credentials	Verify your inbox email and API key from the console
”Connection refused” / handshake error	Wrong encryption mode for the port	Use SSL/TLS on connect for port `465`, or STARTTLS for port `587`
`538` “Must issue a STARTTLS command first”	Plaintext AUTH on port `587`	Enable STARTTLS on port `587` (or use implicit TLS on `465`) before authenticating
”Connection timeout”	Firewall blocking ports	Ensure ports 993 (IMAP) and 465/587 (SMTP) are open
”Sender not authorized”	Wrong From address	Use your inbox’s email address as the From address
”Folder not found”	Folder name typo or unsupported folder	IMAP exposes `INBOX`, `Sent`, `Trash`, and `Spam`. Folder names other than `INBOX` are case-sensitive. Use the API to manage drafts.

When to Use IMAP/SMTP vs API

Use Case	Recommendation
Email client integration	IMAP/SMTP
Simple programmatic sending	SMTP
Full inbox management	API
Real-time notifications	API (Webhooks)
Access to all folders	API
Bulk operations	API

1	import imaplib
2	import os
3	import email
4
5	# Your credentials from AgentMail Console
6	inbox_email = "myinbox@agentmail.to" # From Dashboard → Inboxes
7	api_key = os.getenv("AGENTMAIL_API_KEY") # From Dashboard → API Keys
8
9	# Connect with SSL (required)
10	imap = imaplib.IMAP4_SSL("imap.agentmail.to", 993)
11
12	try:
13	# Authenticate using inbox email as username
14	imap.login(inbox_email, api_key)
15
16	# Select a folder (INBOX, Sent, Trash, or Spam)
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']}")
30	finally:
31	imap.logout()

1	import Imap from "imap";
2
3	// Your credentials from AgentMail Console
4	const inboxEmail = "myinbox@agentmail.to"; // From Dashboard → Inboxes
5	const apiKey = process.env.AGENTMAIL_API_KEY!; // From Dashboard → API Keys
6
7	const imap = new Imap({
8	user: inboxEmail,
9	password: apiKey,
10	host: "imap.agentmail.to",
11	port: 993,
12	tls: true, // SSL required
13	});
14
15	imap.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
23	imap.once("error", (err: Error) => {
24	console.error("IMAP error:", err.message);
25	});
26
27	imap.connect();

1	import smtplib
2	import os
3	from email.mime.text import MIMEText
4	from email.mime.multipart import MIMEMultipart
5
6	# Your credentials from AgentMail Console
7	inbox_email = "myinbox@agentmail.to" # From Dashboard → Inboxes
8	api_key = os.getenv("AGENTMAIL_API_KEY") # From Dashboard → API Keys
9
10	# Create message
11	msg = MIMEMultipart()
12	msg["Subject"] = "Hello from AgentMail"
13	msg["From"] = inbox_email # Use your inbox email as the From address
14	msg["To"] = "recipient@example.com"
15	msg.attach(MIMEText("This is a test email sent via SMTP.", "plain"))
16
17	# Connect with implicit TLS on port 465 and send
18	with 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!")
22
23	# Alternatively, use STARTTLS on port 587:
24	# with smtplib.SMTP("smtp.agentmail.to", 587) as server:
25	# server.starttls()
26	# server.login(inbox_email, api_key)
27	# server.send_message(msg)

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