agent.email

Interface

Read emails from IMAP-enabled email accounts.

AgentEmail Interface

interface AgentEmail {
  readIMAPEmails(
    email: string,
    password: string,
    host?: string,
    port?: number,
    skip?: number,
    limit?: number,
    proxyHost?: string,
    proxyPort?: number,
    proxyUser?: string,
    proxyPassword?: string
  ): Promise<Email[]>;
}

readIMAPEmails

Signature

readIMAPEmails(email: string, password: string, host?: string, port?: number, skip?: number, limit?: number, proxyHost?: string, proxyPort?: number, proxyUser?: string, proxyPassword?: string): Promise<Email[]>

Reads emails from an IMAP server. Useful for automations that need to verify email content (e.g., verification codes, confirmation emails).

Parameter	Type	Description
`email`	string	Email address to read from
`password`	string	Email account password or app-specific password
`host?`	string	IMAP server hostname (auto-detected for common providers)
`port?`	number	IMAP server port (default: 993)
`skip?`	number	Number of emails to skip (for pagination)
`limit?`	number	Maximum number of emails to return
`proxyHost?`	string	Proxy server hostname. Available since app version 2.123 (135)
`proxyPort?`	number	Proxy server port. Available since app version 2.123 (135)
`proxyUser?`	string	Proxy username for authentication. Available since app version 2.123 (135)
`proxyPassword?`	string	Proxy password for authentication. Available since app version 2.123 (135)

Returns Promise<Email[]> — Array of email messages

Read latest emails

const emails = await agent.email.readIMAPEmails(
  "user@gmail.com",
  "app-password-here",
  undefined, // auto-detect host
  undefined, // default port
  0,         // no skip
  10         // limit to 10 emails
);

for (const email of emails) {
  console.log("From:", email.from);
  console.log("Subject:", email.subject);
  console.log("---");
}

Find verification code

const emails = await agent.email.readIMAPEmails(
  "user@gmail.com",
  "app-password",
  undefined, undefined, 0, 5
);

// Find email with verification code
const verificationEmail = emails.find(e =>
  e.subject.includes("Verification") ||
  e.subject.includes("Code")
);

if (verificationEmail) {
  // Extract code from email body
  const codeMatch = verificationEmail.body.match(/\b\d{6}\b/);
  if (codeMatch) {
    console.log("Verification code:", codeMatch[0]);
  }
}

Custom IMAP server

const emails = await agent.email.readIMAPEmails(
  "user@company.com",
  "password",
  "imap.company.com",  // custom host
  993,                  // custom port
  0,
  20
);

Using a proxy server (since v2.123 (135))

const emails = await agent.email.readIMAPEmails(
  "user@gmail.com",
  "app-password",
  undefined,           // auto-detect host
  undefined,           // default port
  0,                   // no skip
  10,                  // limit
  "proxy.example.com", // proxy host
  1080,                // proxy port
  "proxyuser",         // proxy username (optional)
  "proxypassword"      // proxy password (optional)
);

Email

Represents an email message.

interface Email {
  id: string;              // Unique email ID
  subject: string;         // Email subject
  from: string;            // Sender email address
  fromName: string;        // Sender display name
  to: string[];            // Recipients
  cc: string[];            // CC recipients
  bcc: string[];           // BCC recipients
  date: number;            // Timestamp (Unix ms)
  body: string;            // Email body content
  isHtml: boolean;         // true if body is HTML
  isRead: boolean;         // Read status
  hasAttachments: boolean; // Has attachments
  attachmentNames: string[]; // Attachment file names
}

Email Properties

Name	Type	Description
`id`	string	Unique identifier for the email
`subject`	string	Email subject line
`from`	string	Sender's email address
`fromName`	string	Sender's display name
`to`	string[]	Array of recipient email addresses
`cc`	string[]	Array of CC recipient addresses
`bcc`	string[]	Array of BCC recipient addresses
`date`	number	Email timestamp in Unix milliseconds
`body`	string	Email body content (HTML or plain text)
`isHtml`	boolean	Whether the body content is HTML
`isRead`	boolean	Whether the email has been read
`hasAttachments`	boolean	Whether the email has attachments
`attachmentNames`	string[]	Names of attached files

For Gmail accounts, use an App Password instead of your regular password. Regular passwords won't work if 2FA is enabled.