Connect external mail tools: IMAP and SMTP

Connect any tool with the server settings

Every AgentMail inbox is also a standard mailbox, open to any tool that accepts custom mail-server credentials. The same messages are reachable on every path:

Both protocols use the same login:

• Username: the full inbox address, including its domain, for example example@agentmail.to
• Password: an AgentMail API key

Encryption is required on every connection. Match the mode to the port:

• Ports 993 and 465 encrypt from the first byte. Choose the SSL/TLS option in a settings form.
• Port 587 connects in plain text and upgrades with STARTTLS before login. Choose the STARTTLS option.

Before configuring a tool, you can check the settings and credentials together with one short script:

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")

IMAP login ok
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 the table.

Read a mailbox over IMAP

The same messages the API returns are organized into five folders:

• INBOX holds received mail.
• Sent holds every message the inbox sent, through the API or through SMTP.
• Trash and Spam hold trashed and spam mail.
• Drafts is listed for client compatibility and stays empty. Create and manage drafts through the API.

Reading takes the credentials from the settings table plus a folder name. INBOX matches in any casing. The other folder names are exact.

This example opens INBOX read-only and prints the sender and subject of every unread message:

// npm install imap
import Imap from "imap";

const imap = new Imap({
  user: "example@agentmail.to",
  password: process.env.AGENTMAIL_API_KEY!,
  host: "imap.agentmail.to",
  port: 993,
  tls: true,
});

imap.once("ready", () => {
  imap.openBox("INBOX", true, (err, box) => {
    if (err) throw err;
    console.log(`${box.messages.total} messages in INBOX`);

    imap.search(["UNSEEN"], (err, results) => {
      if (err) throw err;
      if (results.length === 0) return imap.end();

      const fetch = imap.fetch(results, { bodies: "HEADER.FIELDS (FROM SUBJECT)" });
      fetch.on("message", (msg) => {
        msg.on("body", (stream) => {
          let header = "";
          stream.on("data", (chunk) => (header += chunk.toString()));
          stream.once("end", () => {
            const parsed = Imap.parseHeader(header);
            console.log(parsed.from[0], "|", parsed.subject[0]);
          });
        });
      });
      fetch.once("end", () => imap.end());
    });
  });
});

imap.once("error", (err: Error) => {
  console.error("IMAP error:", err.message);
});

imap.connect();

Both tabs open the folder read-only, so fetching does not mark anything as seen.

You get complete raw messages, headers and body included, the same messages the API returns.

You <you@example.com> | Re: Quote for 40 units
You <you@example.com> | Following up

The Message-ID header on each message is the value the API calls message_id, so your agent can read over IMAP and act through the API: reply in the message’s thread or download its attachments.

Send over SMTP

SMTP sends from the inbox you log in with. Set the From address to that same inbox address. The server enforces three limits:

• Up to 50 recipients per message, counting To, Cc, and Bcc together.
• Up to 10 MB per message, attachments included.
• Sessions time out after 30 minutes, so open a connection per batch instead of holding one long term.

// npm install nodemailer
import nodemailer from "nodemailer";

const inbox = "example@agentmail.to";

const transporter = nodemailer.createTransport({
  host: "smtp.agentmail.to",
  port: 465,
  secure: true, // for port 587 with STARTTLS: port: 587, secure: false
  auth: {
    user: inbox,
    pass: process.env.AGENTMAIL_API_KEY!,
  },
});

async function sendEmail() {
  const info = await transporter.sendMail({
    from: inbox, // the inbox you log in as
    to: "you@example.com",
    subject: "Hello over SMTP",
    text: "Sent through smtp.agentmail.to.",
  });
  console.log(info.response);
}

sendEmail().catch(console.error);

The server accepts the message with a 250 reply that names the new message’s id:

250 Message queued as <010001a0345cce9e-47649bba-41fc-471d-b19c-2dee3108cfc0-000000@email.amazonses.com>

That id is the message’s message_id everywhere else in AgentMail. The message shows up in your message list with the sent label and in the IMAP Sent folder. Pass the id to the API to get the message or the thread_id of the conversation it started. 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.

Connect a mail client or warm-up tool

Desktop clients such as Thunderbird, Outlook, and Apple Mail take these settings, and so do warm-up platforms such as Instantly and Smartlead. The form labels vary by product, but the values do not:

• Choose the account type called custom, other, or generic IMAP/SMTP. The Google and Microsoft sign-in buttons run an OAuth flow for accounts at those providers, so pick the generic option instead.
• In the incoming mail or IMAP fields, enter the IMAP column of the settings table.
• In the outgoing mail or SMTP fields, enter the SMTP column. Match the security dropdown to the port: SSL/TLS for 465, STARTTLS for 587.
• Set the sender or From address to the same inbox address you entered as the username.

Save the account and run the tool’s connection test. Then send one test message and check that it shows up in the tool’s activity view and in the inbox’s Sent folder.

Clients that support IMAP IDLE get new mail pushed to them as it arrives. The server and client negotiate this automatically.

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. If the connection test fails with a generic error, run the credentials check from the top of this page to tell a credential problem from a form problem.

Next Steps