AI Agent Email Skill (aaes)#

Overview#

This skill provides script-based email operations for an agent. It includes functionalities for managing mailboxes, reading/searching emails, sending/replying/forwarding emails, and managing attachments, allowing agents to perform comprehensive email-related tasks programmatically.

Features#

• IMAP operations: Read, list, mark, move, delete, copy emails
• SMTP operations: Send, reply, forward emails with attachments
• Folder management: Create, delete, rename, list mailboxes
• Dual-format bodies: Supports both plain-text and HTML, with automatic fallback generation
• Attachment handling: Supports base64-encoded attachments
• Multi-account support: Configure multiple accounts
• Authentication: Password or OAuth2 via environment variables (auto-detected)
• Signatures: Automatic signature appending to outgoing emails
• Thread support: Proper In-Reply-To and References header handling

When to use#

Use this skill when you need an agent to:

• Check inbox for new emails and summarize them
• Read specific emails and extract content
• Send new emails with attachments
• Reply to or forward emails
• Organize emails by moving/copying between folders
• Create or manage mailbox folders
• Mark emails as read/unread, flagged, spam, or junk

Requirements#

• Python 3.14+
• IMAP/SMTP access to your email provider
• Network access to email servers

Configuration#

Basic Setup#

Configure this skill with ./scripts/config.toml:

1. Copy ./config.default.toml to ./scripts/config.toml.
2. Edit ./scripts/config.toml - fill in email address and server addresses.

Authentication Setup#

Only one authentication method is required, configured via environment variables.

Password-based authentication

VariableDescriptionEMAIL_USERNAMELogin username (required)EMAIL_PASSWORDUser password or app passwordbash

# Linux/Mac
export EMAIL_USERNAME="me"
export EMAIL_PASSWORD="my-password"

# Windows (PowerShell)
$env:EMAIL_USERNAME="me"
$env:EMAIL_PASSWORD="my-password"

# Windows (CMD)
set EMAIL_USERNAME=me
set EMAIL_PASSWORD=my-password

OAuth2 authentication

VariableDescriptionEMAIL_OAUTH2_CLIENT_IDOAuth2 client IDEMAIL_OAUTH2_CLIENT_SECRETOAuth2 client secretEMAIL_OAUTH2_REFRESH_TOKENOAuth2 refresh tokenEMAIL_OAUTH2_TOKEN_URLOAuth2 token endpoint URLbash

# Linux/Mac
export EMAIL_OAUTH2_CLIENT_ID="xxx"
export EMAIL_OAUTH2_CLIENT_SECRET="xxx"
export EMAIL_OAUTH2_REFRESH_TOKEN="xxx"
export EMAIL_OAUTH2_TOKEN_URL="https://oauth2.example.com/token"

# Windows (PowerShell)
$env:EMAIL_OAUTH2_CLIENT_ID="xxx"
$env:EMAIL_OAUTH2_CLIENT_SECRET="xxx"
$env:EMAIL_OAUTH2_REFRESH_TOKEN="xxx"
$env:EMAIL_OAUTH2_TOKEN_URL="https://oauth2.example.com/token"

# Windows (CMD)
set EMAIL_OAUTH2_CLIENT_ID=xxx
set EMAIL_OAUTH2_CLIENT_SECRET=xxx
set EMAIL_OAUTH2_REFRESH_TOKEN=xxx
set EMAIL_OAUTH2_TOKEN_URL="https://oauth2.example.com/token"

Test#

bash

# Linux/Mac
echo '{"requestId":"test","schemaVersion":"1.0","data":{"maxResults":5}}' | python3 scripts/mail_list.py

# Windows (PowerShell)
echo '{"requestId":"test","schemaVersion":"1.0","data":{"maxResults":5}}' | python scripts/mail_list.py

# Windows (CMD)
echo "{\"requestId\":\"test\",\"schemaVersion\":\"1.0\",\"data\":{\"maxResults\":5}}" | python scripts/mail_list.py

Data Exchange Contract#

Overview#

All scripts follow the same JSON-over-stdin contract:

1. Agent sends one JSON object to stdin
2. Script writes one JSON object to stdout
3. Logs and diagnostics are written to stderr

Request Schema#

json

{
  "requestId": "optional-trace-id",
  "schemaVersion": "1.0",
  "account": "optional-account-name-in-config",
  "data": {}
}

Success Response Schema#

json

{
  "ok": true,
  "requestId": "same-as-request",
  "schemaVersion": "1.0",
  "data": {}
}

Error Response Schema#

json

{
  "ok": false,
  "requestId": "same-as-request",
  "schemaVersion": "1.0",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

Error CodeDescriptionVALIDATION_ERRORInvalid input data or parametersCONFIG_ERRORConfiguration file missing or invalidAUTH_ERRORAuthentication failedNETWORK_ERRORNetwork connection failedMAIL_OPERATION_ERRORIMAP/SMTP operation failedMAILBOX_ERRORMailbox selection or management failedINTERNAL_ERRORUnexpected internal error

Scripts#

folder_create.py#

Create mailbox folder.

Request fieldsnamestring, requiredResponse fieldsaccountAccount name usednameFolder name createdcreated``true on success

folder_delete.py#

Delete mailbox folder.

Request fieldsnamestring, requiredResponse fieldsaccountAccount name usednameFolder name deleteddeleted``true on success

folder_list.py#

List mailbox folders.

Request fields(none)Response fieldsaccountAccount name usedmailboxesArray of folder objects

folder_rename.py#

Rename mailbox folder.

Request fieldsoldNamestring, requirednewNamestring, requiredResponse fieldsaccountAccount name usedoldNameOriginal folder namenewNameNew folder namerenamed``true on success

mail_copy.py#

Copy email(s) between folders.

Request fieldsuidsstring[] or comma-separated stringsourceFolderoptional, default INBOX``targetFolderrequiredResponse fieldsaccountAccount name useduidsUIDs copiedsourceFolderSource foldertargetFolderTarget foldercopied``true on success

mail_delete.py#

Delete email(s).

Request fieldsuidsstring[] or comma-separated stringfolderoptional, default INBOX``expungeboolean, default falseResponse fieldsaccountAccount name useduidsUIDs deletedfolderFolder namedeleted``true on successexpunged``true if hard deleted

mail_forward.py#

Forward email with optional additions.

Request fieldsuidstring, requiredfolderoptional, default INBOX``tostring or string[], requiredccoptionalbccoptionalbodyTextoptional, prepended to forwarded contentbodyHtmloptionalattachmentsoptionalResponse fieldsaccountAccount name usedforwarded``true on successuidOriginal email UIDtoRecipientsccCC recipientssubjectForwarded subject

Automatically includes original email and attachments.

mail_mark.py#

Mark email(s) with flags.

Request fieldsuidsstring[] or comma-separated string, requiredmarkType``read, unread, flag, unflag, spam, notspam, junk, notjunk, requiredfolderoptional, default INBOXResponse fieldsaccountAccount name useduidsUIDs markedmarkTypeMark type appliedmarked``true on success

mail_move.py#

Move email(s) between folders.

Request fieldsuidsstring[] or comma-separated stringsourceFolderoptional, default INBOX``targetFolderrequiredResponse fieldsaccountAccount name useduidsUIDs movedsourceFolderSource foldertargetFolderTarget foldermoved``true on success

mail_read.py#

Read email content and metadata.

Request fieldsuidstring, requiredfolderoptional, default INBOXResponse fieldsaccountAccount name useduidEmail UIDsubjectEmail subjectfromSendertoRecipientsccCC recipientsdateEmail datebodyTextPlain text bodybodyHtmlHTML bodyattachmentsAttachment listtagsCombined flags and labels

Marks message as read after fetch.

mail_reply.py#

Reply to email.

Request fieldsuidstring, requiredfolderoptional, default INBOX``bodyTextoptionalbodyHtmloptionalreplyAllboolean, default false``priority``high, normal, low``attachmentsoptionalResponse fieldsaccountAccount name useduidOriginal email UIDfolderOriginal email foldersent``true on successtoReply recipientsccCC recipientsattachmentCountNumber of attachmentspriorityPriority level ( high, normal, low)readReceipt``true if read receipt requestedinReplyToIn-Reply-To message IDreferencesReferences header valuesubjectReply subject

mail_list.py#

List emails using IMAP search.

Request fieldsqueryoptional, default UNSEEN``folderoptional, default INBOX``maxResultsoptional, default 10Response fieldsaccountAccount name usedfolderFolder searchedquerySearch queryuidsMatching UIDscountResults returnedtotalCountTotal matcheshasMoreMore results availablesummaryEmail summariesQueryDescriptionUNSEENUnread messagesFROM user@example.comFrom senderSUBJECT "keyword"Subject containsSINCE 2024-01-01Since dateALLAll messages

mail_send.py#

Send new email.

Request fieldstostring or string[], requiredsubjectstring, requiredbodyTextoptionalbodyHtmloptionalccoptionalbccoptionalpriority``high, normal, low``attachmentsoptionalResponse fieldsaccountAccount name usedsent``true on successtoRecipientsccCC recipientsbccCountNumber of BCC recipientsattachmentCountNumber of attachmentspriorityPriority level ( high, normal, low)readReceipt``true if read receipt requestedinReplyToIn-Reply-To message IDreferencesReferences header valuesubjectSent subject

Examples#

List new emails#

bash

echo '{"requestId":"test","schemaVersion":"1.0","data":{"maxResults":10}}' | python3 scripts/mail_list.py

Read email by UID#

json

{ "requestId": "read", "schemaVersion": "1.0", "data": { "uid": "123" } }

List from sender#

json

{
  "requestId": "search",
  "schemaVersion": "1.0",
  "data": { "query": "FROM boss@example.com" }
}

Send email#

json

{
  "requestId": "send",
  "schemaVersion": "1.0",
  "data": {
    "to": ["user@example.com"],
    "subject": "Hello",
    "bodyText": "Hello world!"
  }
}

Reply to email#

json

{
  "requestId": "reply",
  "schemaVersion": "1.0",
  "data": { "uid": "123", "bodyText": "Thanks!" }
}

Mark and move#

json

{"requestId":"mark","schemaVersion":"1.0","data":{"uids":"123","markType":"read"}}
{"requestId":"move","schemaVersion":"1.0","data":{"uids":"123","targetFolder":"Archive"}}

Troubleshooting#

AUTH_ERROR#

• If password auth: Ensure both EMAIL_USERNAME and EMAIL_PASSWORD are set
• If OAuth2 auth: All four variables required: EMAIL_OAUTH2_CLIENT_ID, EMAIL_OAUTH2_CLIENT_SECRET, EMAIL_OAUTH2_REFRESH_TOKEN, EMAIL_OAUTH2_TOKEN_URL
• For 2FA accounts, use app password for EMAIL_PASSWORD
• OAuth2 takes priority if all four EMAIL_OAUTH2_* variables are set

NETWORK_ERROR#

• Verify IMAP port 993 (SSL) or 143 (STARTTLS)
• Verify SMTP port 465 (SSL) or 587 (STARTTLS)
• Check firewall settings

CONFIG_ERROR#

• Ensure config.toml exists and is valid TOML
• Check email, imap.host, smtp.host are configured

Security Warnings#

⚠️ SSL Verification: Setting ssl_verify = false in config disables certificate validation and exposes connections to man-in-the-middle attacks. Only disable for local development/testing.

⚠️ IMAP Injection Protection: User-provided search queries are validated against a whitelist of safe commands. Custom queries containing ()"; characters will be rejected.

Debugging#

Check stderr for detailed error logs with code, message, and details.