IMAP and SMTP

AgentPost provides SMTP and IMAP protocol servers for standard email client access. Use these when you need to connect a traditional email client (Thunderbird, Apple Mail, Outlook) or when your agent framework supports SMTP/IMAP natively.

When to use SMTP/IMAP vs REST API

The REST API is preferred for programmatic access. SMTP/IMAP are available for compatibility with standard email clients and legacy systems.

SMTP (Sending)

Use SMTP to send email from any standard email client or SMTP library.

Connection settings

Example: Sending with Node.js (nodemailer)

import nodemailer from 'nodemailer';

const transporter = nodemailer.createTransport({
  host: 'smtp.agent-post.dev',
  port: 465,
  secure: true, // implicit TLS
  auth: {
    user: 'support-a1b2c3@shared.agent-post.dev',
    pass: 'ap_sk_your_api_key_here',
  },
});

await transporter.sendMail({
  from: 'support-a1b2c3@shared.agent-post.dev',
  to: 'customer@example.com',
  subject: 'Your ticket has been resolved',
  text: 'Hi, your support ticket #4821 has been resolved.',
});

Example: Sending with Python (smtplib)

import smtplib
from email.mime.text import MIMEText

msg = MIMEText("Hi, your support ticket #4821 has been resolved.")
msg["Subject"] = "Your ticket has been resolved"
msg["From"] = "support-a1b2c3@shared.agent-post.dev"
msg["To"] = "customer@example.com"

with smtplib.SMTP_SSL("smtp.agent-post.dev", 465) as server:
    server.login(
        "support-a1b2c3@shared.agent-post.dev",
        "ap_sk_your_api_key_here",
    )
    server.send_message(msg)

IMAP (Receiving)

Use IMAP to read email from any standard email client or IMAP library.

Connection settings

Virtual folders

AgentPost maps inbox data to standard IMAP folders:

Example: Reading with Python (imaplib)

import imaplib
import email

imap = imaplib.IMAP4_SSL("imap.agent-post.dev", 993)
imap.login(
    "support-a1b2c3@shared.agent-post.dev",
    "ap_sk_your_api_key_here",
)

imap.select("INBOX")
status, messages = imap.search(None, "UNSEEN")

for msg_id in messages[0].split():
    status, data = imap.fetch(msg_id, "(RFC822)")
    msg = email.message_from_bytes(data[0][1])
    print(f"From: {msg['From']}")
    print(f"Subject: {msg['Subject']}")

imap.logout()

Client configuration presets

Thunderbird

Apple Mail

1. Open Mail > Add Account > Other Mail Account
2. Enter your inbox email and API key as password
3. Set incoming server to imap.agent-post.dev
4. Set outgoing server to smtp.agent-post.dev
5. Select SSL for both connections

Generic client

For any other email client, use the IMAP and SMTP connection settings listed above. Ensure TLS/SSL is enabled for both connections.

Credential CSV export

Export IMAP/SMTP credentials for all your inboxes as a CSV file:

const csv = await client.inboxes.exportCredentials();
// Returns CSV with columns: email, imap_host, imap_port, smtp_host, smtp_port, username, password

csv = client.inboxes.export_credentials()

curl "https://api.agent-post.dev/api/v1/inboxes/credentials/export" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -o credentials.csv

SMTP authentication and scopes

SMTP authentication uses the inbox email as the username and an organization API key as the password. The API key must have messages:write scope to send via SMTP.

IMAP authentication follows the same pattern. The API key must have messages:read scope to read via IMAP.

IMAP IDLE (push notifications)

The IMAP server supports the IDLE extension for real-time push notifications. When your client enters IDLE mode, it will be notified immediately when new messages arrive -- no polling required.

Tips

• SMTP/IMAP servers use TLS by default. Unencrypted connections are not supported.
• Each inbox has its own IMAP mailbox. You cannot access all inboxes from a single IMAP connection.
• SMTP rate limits and send-block rules apply to SMTP connections just like REST API sends.
• For programmatic access, the REST API is more efficient than SMTP/IMAP.
• The credential CSV export is useful for setting up multiple email clients quickly.
• IMAP connection limits are enforced per inbox at login time.