jmap-email_skill

Overview

This skill enables JMAP email operations using Node.js and the jmap-jam library. It provides ready-made scripts to list, search, read, move, and delete emails against JMAP-compatible servers like FastMail, Cyrus IMAP, and Stalwart. Set a few environment variables and run the scripts for fast programmatic inbox management.

How this skill works

Scripts use the JMAP session URL, a bearer token, and an account ID (optional) to authenticate and call JMAP endpoints. Common scripts expose filtered listing, keyword search previews, full-message retrieval, mailbox listing, message moves, and deletions. Each script accepts CLI flags (for example --unread, --mailbox, --from, --limit) and prints compact, human-readable output.

When to use it

• When you need to search or filter large volumes of email programmatically.
• To triage and move batches of messages across mailboxes with scripts.
• When building automation or integrations that require reliable JMAP access.
• To inspect full email content for specific message IDs.
• When migrating or organizing mail on FastMail, Cyrus, or other JMAP servers.

Best practices

• Set JMAP_SESSION_URL, JMAP_BEARER_TOKEN, and optionally JMAP_ACCOUNT_ID in your environment before running scripts.
• Use --limit and --mailbox flags to scope queries and avoid large responses.
• Preview matches with search-keywords.ts, then fetch full content with get-email.ts only for selected IDs.
• Group IDs by destination mailbox and call move-by-ids.ts once per mailbox to minimize API calls.
• Keep an audit or log of moved and deleted message IDs to support reversions or debugging.

Example use cases

• Batch triage: list recent unread messages, ask a user for mailbox choices, then move messages by ID.
• Automated receipt collection: search for keywords like invoice or receipt and export previews for accounting.
• Sender cleanup: list messages from a specific sender and archive or delete them in bulk.
• Mailbox mapping: list-mailboxes.ts to discover folder names, then move messages into a target mailbox.
• Forensic read: use get-email.ts to retrieve full RFC-style content for a given message ID.