Send, draft, read, search, count emails, and download attachments. Enable by including "email_*" in the agent’s allowedTools array.
SMTP (send): Uses nodemailer. Credentials from agent vault ("email" entry with type "smtp"), env vars (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM), or per-call parameter overrides.IMAP (read/search): Uses imapflow. Credentials from agent vault ("email-inbox" entry with type "imap") or env vars (IMAP_HOST, IMAP_PORT, IMAP_USER, IMAP_PASS).
The easiest way to configure email credentials is through the onboarding wizard: polpo agent onboard <name>. Step 4 walks you through SMTP and IMAP setup, creates vault entries with ${ENV_VAR} references, and adds email_* to allowedTools automatically. See Onboarding walkthrough.
email_draft — Save Draft Email
Create an email draft and save it to the IMAP Drafts folder.
Parameters
| Parameter | Type | Required | Description |
|---|
to | string | string[] | no | Recipient email address(es) |
subject | string | no | Email subject line |
body | string | no | Draft body content |
html | boolean | no | Save body as HTML draft (auto-detected if omitted) |
cc | string | string[] | no | CC recipient(s) |
bcc | string | string[] | no | BCC recipient(s) |
from | string | no | Sender address (defaults to SMTP_FROM or IMAP user) |
reply_to | string | no | Reply-to address |
attachments | array of {path, filename?} | no | File attachments |
folder | string | no | Drafts folder path (default: auto-detect, then "Drafts") |
imap_host | string | no | IMAP host (overrides vault/env) |
imap_port | number | no | IMAP port (overrides vault/env) |
imap_user | string | no | IMAP username (overrides vault/env) |
imap_pass | string | no | IMAP password (overrides vault/env) |
imap_tls | boolean | no | IMAP TLS setting (overrides vault/env) |
Returns
Confirmation with the target folder and append metadata.
Notes
- Drafts are saved via IMAP
APPEND with the \\Draft flag
- If
folder is omitted, Polpo auto-detects the mailbox with special-use \\Drafts, then falls back to Drafts
- Attachment paths are sandboxed exactly like
email_send
email_send — Send Email
Send an email via SMTP.
Parameters
| Parameter | Type | Required | Description |
|---|
to | string | string[] | yes | Recipient email address(es) |
subject | string | yes | Email subject line |
body | string | yes | Email body content |
html | boolean | no | Send as HTML email (auto-detected if omitted) |
cc | string | string[] | no | CC recipient(s) |
bcc | string | string[] | no | BCC recipient(s) |
from | string | no | Sender address (overrides vault/env) |
reply_to | string | no | Reply-to address |
attachments | array of {path, filename?} | no | File attachments |
smtp_host | string | no | SMTP host (overrides vault/env) |
smtp_port | number | no | SMTP port (overrides vault/env) |
smtp_user | string | no | SMTP username (overrides vault/env) |
smtp_pass | string | no | SMTP password (overrides vault/env) |
smtp_secure | boolean | no | Use TLS (overrides auto-detection) |
Returns
Confirmation with the message ID and accepted recipients.
Notes
- Credential resolution order: tool parameters > agent vault > environment variables
- Port 465 uses implicit TLS; all other ports use STARTTLS
- When
html is omitted, the body is auto-detected — if it contains HTML tags, it’s sent as HTML
email_verify — Verify SMTP Connection
Test that the SMTP connection and credentials are valid without sending an email.
Parameters
| Parameter | Type | Required | Description |
|---|
smtp_host | string | no | SMTP host (overrides vault/env) |
smtp_port | number | no | SMTP port (overrides vault/env) |
smtp_user | string | no | SMTP username (overrides vault/env) |
smtp_pass | string | no | SMTP password (overrides vault/env) |
Returns
Success or failure message indicating whether the SMTP connection was established and authenticated.
email_list — List Emails
List recent emails from an IMAP mailbox.
Parameters
| Parameter | Type | Required | Description |
|---|
folder | string | no | Mailbox folder (default: "INBOX") |
limit | number | no | Max emails to return (default: 20) |
unseen_only | boolean | no | Only return unread emails (default: false) |
Returns
List of emails with UID, subject, from address, date, and read/unread status.
email_read — Read Email
Read a single email by its UID. Returns the full email content plus attachment metadata (filename, size, MIME type, part ID) for any attachments present.
Parameters
| Parameter | Type | Required | Description |
|---|
uid | number | yes | Email UID (from email_list) |
folder | string | no | Mailbox folder (default: "INBOX") |
mark_read | boolean | no | Mark as read after fetching (default: true) |
download_attachments | boolean | no | Download all attachments to the task output directory (default: false). Use email_download_attachment for selective download. |
Returns
Full email content: subject, from, to, date, text/HTML body, and an attachments section listing each attachment with:
- Part number — the MIME part ID needed for
email_download_attachment
- Filename — original filename from the email
- MIME type — e.g.
application/pdf, image/png
- Size — approximate size in KB
If download_attachments is true, also includes the list of file paths where attachments were saved.
Notes
- Attachment metadata is extracted from the IMAP
bodyStructure response — no additional download is needed just to see what’s attached
- Use
email_download_attachment to selectively download individual attachments by part number
email_download_attachment — Download Email Attachment
Download a specific attachment from an email by UID and MIME part number. Use email_read first to see the list of attachments with their part numbers.
Parameters
| Parameter | Type | Required | Description |
|---|
uid | number | yes | Email UID (from email_list or email_read) |
part | string | yes | MIME part number of the attachment (from email_read attachment list, e.g. "2", "1.2") |
folder | string | no | Mailbox folder (default: "INBOX") |
filename | string | no | Override the output filename (default: uses the attachment’s original filename) |
output_path | string | no | Custom output path relative to working directory (default: task output directory) |
Returns
Confirmation with the saved file path, size, content type, and part number.
Notes
- The output file is sandboxed to the agent’s allowed paths
- If no
output_path is specified, the file is saved to the task’s output directory
- Typical workflow:
email_list → email_read (see attachments) → email_download_attachment (download specific ones)
email_search — Search Emails
Search emails by criteria.
Parameters
| Parameter | Type | Required | Description |
|---|
from | string | no | Search by sender address |
to | string | no | Search by recipient address |
subject | string | no | Search by subject (substring) |
since | string | no | Search emails since date (YYYY-MM-DD) |
before | string | no | Search emails before date (YYYY-MM-DD) |
body | string | no | Search by body text (substring) |
answered | boolean | no | Filter by answered flag (true = answered, false = unanswered) |
folder | string | no | Mailbox folder (default: "INBOX") |
limit | number | no | Max results (default: 20) |
Returns
List of matching emails with UID, subject, from, and date.
Notes
- At least one search criterion is required
- Multiple criteria are AND-ed together (e.g.
from + since returns emails from that sender after that date)
- Use
since + before together for date range queries
email_count — Count Emails
Count emails matching filters without downloading message contents. Uses IMAP SEARCH internally and returns the result count.
Parameters
| Parameter | Type | Required | Description |
|---|
from | string | no | Count emails from sender |
to | string | no | Count emails to recipient |
subject | string | no | Count emails matching subject (substring) |
since | string | no | Count emails since date (YYYY-MM-DD) |
before | string | no | Count emails before date (YYYY-MM-DD) |
body | string | no | Count emails matching body text (substring) |
answered | boolean | no | Filter by answered flag (true = answered, false = unanswered) |
unseen_only | boolean | no | Count only unread emails (default: false) |
folder | string | no | Mailbox folder (default: "INBOX") |
Returns
Total count and unread count of emails matching the filters.
Notes
- With no filters, counts all emails in the folder
- No message content is downloaded — uses IMAP SEARCH for efficient counting
- Useful for aggregations: “how many emails from X this month?”, “how many unread?”
