AgentEmail

Interface

Read emails via IMAP protocol

Access email methods through agent.email. Allows reading emails from IMAP-enabled email accounts.

AgentEmail Interface

TypeScript

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

Methods

`readIMAPEmails()`

TypeScript

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

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

Parameters

Name	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

Returns

Promise<Email[]>Array of email messages

Examples

Read latest emails

TypeScript

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

TypeScript

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

TypeScript

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

Email Type

Email

Represents an email message.

TypeScript

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

Property	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

Security Note

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