Agent skill

Email

Send and read email from the iii engine — SMTP send, IMAP read, and real-time IDLE push as a subscribable trigger type.

Apache-2.0Auto-check passedBackend & APIs

Install Email

skills CLI

$ npx skills add iii-hq/workers --skill email -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install iii-hq/workers email --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/iii-hq/workers.git skills-src && mkdir -p .claude/skills && cp -r skills-src/email/skills .claude/skills/email && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "email" agent skill from https://github.com/iii-hq/workers/tree/main/email/skills into .claude/skills/email/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "email", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/iii-hq/workers/tree/main/email/skills

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add iii-hq/workers --skill email -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install iii-hq/workers email --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/iii-hq/workers.git skills-src && mkdir -p .agents/skills && cp -r skills-src/email/skills .agents/skills/email && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "email" agent skill from https://github.com/iii-hq/workers/tree/main/email/skills into .agents/skills/email/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "email", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add iii-hq/workers --skill email -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install iii-hq/workers email --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/iii-hq/workers.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/email/skills .cursor/skills/email && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "email" agent skill from https://github.com/iii-hq/workers/tree/main/email/skills into .cursor/skills/email/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "email", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/iii-hq/workers.git --path email/skills

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add iii-hq/workers --skill email -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install iii-hq/workers email --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/iii-hq/workers.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/email/skills .gemini/skills/email && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "email" agent skill from https://github.com/iii-hq/workers/tree/main/email/skills into .gemini/skills/email/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "email", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install iii-hq/workers email

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add iii-hq/workers --skill email -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/iii-hq/workers.git skills-src && mkdir -p .github/skills && cp -r skills-src/email/skills .github/skills/email && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "email" agent skill from https://github.com/iii-hq/workers/tree/main/email/skills into .github/skills/email/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "email", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add iii-hq/workers --skill email -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install iii-hq/workers email --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/iii-hq/workers.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/email/skills .opencode/skills/email && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "email" agent skill from https://github.com/iii-hq/workers/tree/main/email/skills into .opencode/skills/email/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "email", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: email
GitHub stars: 113
Token cost: ~2.1k tokens
SKILL.md length: 1,014 words
Files: 1
Skills in repo: 19
Repo updated: Oct 10, 2026
First seen: Oct 7, 2026
Licence: Apache-2.0

At a glance

Send and read email from the iii engine — SMTP send, IMAP read, and real-time IDLE push as a subscribable trigger type.

Works in 2 steps: Register a handler:… → Register the trigger
Tasks that involve Transactional email
SKILL.md covers When to Use, Boundaries, Functions and Reactive triggers, plus 1 more section
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Email is an agent skill from iii-hq/workers. Send and read email from the iii engine — SMTP send, IMAP read, and real-time IDLE push as a subscribable trigger type. Credentials live in harness/auth-credentials; this worker fetches them on every connect.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering Transactional email. The licence is Apache-2.0.

When your agent uses it

Tasks that involve Transactional email

Example prompts

“/email”

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

What it can do on your machine

Read from SKILL.md and the folder at commit ebfe027. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are typescript and json).
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Email loads about 2.1k tokens when it runs. Until then it costs about 55 tokens; SKILL.md has 1,014 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~55
When it runs · the whole SKILL.md, loaded when a task matches: ~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from iii-hq/workers at commit ebfe027, republished under its Apache-2.0 licence (© iii-hq). 1,014 words, ~2,104 tokens.

Download SKILL.mdSave it as .claude/skills/email/SKILL.md (or your agent's skills folder).

name: email
description: Send and read email from the iii engine — SMTP send, IMAP read, and real-time `IDLE` push as a subscribable trigger type. Credentials live in `harness/auth-credentials`; this worker fetches them on every connect.

email

The email worker speaks SMTP and IMAP through persistent per-account connections. Every callable surface lives under the email::* namespace. The transport is chosen per account in config.yaml — provider: smtp for send-only accounts, provider: imap for two-way accounts that also need to read and react to inbound mail.

The worker refuses to fall back to polling. If an IMAP server does not advertise the IDLE capability, the supervisor fails at startup with E610. Inbound messages flow through the email::new-mail trigger type, fanned out by an IDLE-driven dispatcher the moment a server-side EXISTS notification lands. Credentials never live in this worker — every IMAP login and every email::send calls auth::get_token against harness/auth-credentials under provider key email::<account>.

When to Use

An agent needs to send a transactional email right now (email::send).
You need to enumerate configured accounts and their capabilities so an LLM picks the right account field (email::accounts::list).
You need to page recent messages in an IMAP folder by UID with a stable cursor (email::list).
You need the full parsed body of one message plus attachment part refs (email::get).
You need to stream IMAP SEARCH results as NDJSON as the server returns matches (email::search).
You need to add or remove a system flag — \Seen, \Flagged, \Answered, \Deleted, \Draft (email::flag).
You need to move a message to another folder atomically with RFC 6851 UID MOVE (email::move).
You need to stream an attachment's raw bytes onto a response channel with no in-memory buffering (email::attachment::get).
You need to react to inbound mail the instant it lands in a configured (account, folder) (email::new-mail trigger type).

Boundaries

Not a mail server — this is a client. Bring your own SMTP and IMAP endpoints.
Not an OAuth flow runner in 0.1.0 — use app-password style credentials via harness/auth-credentials until the OAuth follow-up PR.
Not a polling fallback — IMAP servers without IDLE fail fast with E610 so the failure stays visible instead of silently degrading.
Not a credential store — every connect re-fetches the secret from harness/auth-credentials. Pair the two workers; deploying email alone is unsupported.
email::flag with flag: "deleted" does NOT expunge — use email::move to a Trash folder for visible deletion.
email::search and email::attachment::get use a streaming response channel; they're invoked by sibling workers passing a StreamChannelRef, not directly from iii trigger.

Functions

email::send — deliver a message via the account's SMTP transport (STARTTLS or plain on a trusted network).
email::accounts::list — enumerate configured accounts with provider, from, can_send, can_read, and folders.
email::list — page recent UIDs in a folder, newest first, with next_since_uid cursor.
email::get — fetch one message by UID; returns parsed html, text, headers, and an attachments[] list of part refs.
email::search — stream IMAP SEARCH results as NDJSON frames onto a StreamChannelRef; one header-summary object per match.
email::flag — add or remove a system flag on a UID via UID STORE +FLAGS.SILENT / -FLAGS.SILENT.
email::move — move a UID to another folder with RFC 6851 UID MOVE; falls back to COPY + STORE \Deleted when the server lacks MOVE.
email::attachment::get — stream attachment bytes by part_id onto a StreamChannelRef chunk-by-chunk; no in-memory buffering.

SMTP send timeout is limits.send_timeout_ms (default 30 s). IMAP connect timeout is limits.imap_connect_timeout_ms (default 15 s). Total recipients across to + cc + bcc cap at limits.max_recipients (default 100). Each attachment caps at limits.max_attachment_bytes (default 25 MiB).

Stream-source attachments (source.kind = "stream") return E699 in 0.1.0; use source.kind = "base64" until the symmetric attachment-send path lands.

Reactive triggers

Register an email::new-mail trigger when a function should fire automatically the moment a new message arrives in a configured (account, folder) — without polling with email::list.

Reach for it when:

A support workflow should kick off the instant a ticket email lands.
A harness session should ingest new mail as an additional turn.
An archival worker should mirror inbound mail into a database.

Do not bind when:

The account is provider: smtp (send-only); only provider: imap accounts open an IDLE listener.
You only need to act on outbound mail — email::send already gives you the SMTP response synchronously.

Show full SKILL.md (368 more words)Show less

How to bind

typescript

iii.registerTrigger({
  type: 'email::new-mail',
  function_id: 'my-worker::on-mail',
  config: {
    account: 'support',
    folder: 'INBOX',
    handler_timeout_ms: 30000,
  },
})

Config: account (required, must be a configured account with an imap: block), folder (default "INBOX", must appear in config.accounts.<name>.imap.folders), handler_timeout_ms (default 30 000).

Event payload per inbound message:

json

{
  "account":    "support",
  "folder":     "INBOX",
  "uid":        12345,
  "message_id": "<abc@mx.example.com>",
  "from":       "alice@example.com",
  "subject":    "Ticket #42",
  "snippet":    "first ~200 chars of body",
  "ts":         "2026-05-28T10:14:00+00:00"
}

The dispatch is event-driven off the IMAP server's EXISTS push — within milliseconds of a new message landing in the watched folder.

Delivery semantics

Best-effort, at-most-once. The dispatcher fires iii.trigger per subscriber and waits up to handler_timeout_ms. There is no upstream durable queue: IMAP IDLE is a wakeup mechanism, not a delivery guarantee.

A subscriber handler that panics, times out, or returns an error is logged and skipped — the event is NOT redelivered.
If the worker is down when a message lands, no email::new-mail event fires for it. On reconnect the supervisor sets the high-water mark to the current UIDNEXT - 1; UIDs that arrived during downtime are reachable via email::list but do NOT replay as events.
For at-least-once / replay, write each email::new-mail event to a durable store from your handler (database::execute, storage::putObject, …) before doing meaningful work, and use email::list with a persisted since_uid cursor to catch up on downtime gaps.

Errors

Stable across the trigger boundary. Match on the code field of the returned envelope.

Code	When
`E600`	Unknown account name
`E601`	`email::send` with empty `to`
`E602`	Total recipients over `limits.max_recipients`
`E603`	Account missing the required transport block
`E604`	`email::send` with neither `html` nor `text`
`E605`	Attachment over `limits.max_attachment_bytes`
`E606`	`auth::get_token` upstream call failed
`E607`	No credential stored for the account
`E608`	Credential payload missing `username` / `password`
`E609`	Address parse / MIME build failure
`E610`	IMAP server lacks IDLE — refusing to fall back to polling
`E612`	IMAP `UID SEARCH` failed
`E613`	Folder not in account's `imap.folders` config
`E614`	IMAP connect / TLS handshake failed
`E615`	Plain (non-TLS) IMAP refused
`E616`	IMAP login failed
`E617`	IMAP `SELECT` failed
`E619`	IMAP body fetch / MIME parse failed
`E620`	SMTP send failed
`E621`	Response channel close failed
`E622`	Unknown flag name
`E623`	IMAP `STORE` failed
`E624`	IMAP `COPY` / `STORE \Deleted` fallback failed
`E625`	IMAP attachment-part fetch failed
`E626`	Attachment payload malformed (e.g. invalid base64)
`E627`	`email::move` partial: copy succeeded but `STORE \Deleted` failed — message in BOTH folders, reconcile
`E699`	Not yet implemented in 0.1.0

Files

Just SKILL.md in email/skills of iii-hq/workers.

Open the folder on GitHubat commit ebfe027

Compare with similar skills

Email next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Email compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Email this skilliii-hq/workers	113	—	~2.1k	Automated safety check: Pass	Apache-2.0	today
Stripe Projectsfossasia/eventyay	1.7k	5 repos	~2k	Automated safety check: Notes	Apache-2.0	today
WooCommerce Email Editor Developmentwoocommerce/woocommerce	11k	—	~893	Automated safety check: Pass	Custom licence	today
Email Best Practicesviclafouch/meme-studio	110	7 repos	~787	Automated safety check: Pass	None	6 mo ago
React Emailviclafouch/meme-studio	110	2 repos	~3.6k	Automated safety check: Pass	MIT	6 mo ago
Pinme Emailglitternetwork/pinme	3.8k	—	~1.2k	Automated safety check: Pass	MIT	28 days ago

Similar skills

Stripe Projects
fossasia/eventyay
A skill your agent uses when the user wants to provision infrastructure or third-party services using Stripe Projects.
1.7k GitHub starsUsed in 5 repos~2k tokens
Backend & APIsAuto-check: notes
WooCommerce Email Editor Development
woocommerce/woocommerce
Sets up a local environment for the WooCommerce block email editor, with a watcher, Mailpit email capture and build and test commands for its PHP and JS packages.
11k GitHub stars~893 tokensUpdated today
Backend & APIsAuto-check passed
Email Best Practices
viclafouch/meme-studio
A skill your agent uses when building email features, emails going to spam, high bounce rates, setting up SPF/DKIM/DMARC authentication, implementing email capture, ensuring compliance (CAN-SPAM…
110 GitHub starsUsed in 7 repos~787 tokens
Backend & APIsAuto-check passed
React Email
viclafouch/meme-studio
A skill your agent uses when creating HTML email templates with React components - welcome emails, password resets, notifications, order confirmations, newsletters, or transactional emails.
110 GitHub starsUsed in 2 repos~3.6k tokens
Backend & APIsAuto-check passed
Pinme Email
glitternetwork/pinme
A skill your agent uses when a PinMe project (Worker TypeScript) needs to integrate email sending (sendemail).
3.8k GitHub stars~1.2k tokensUpdated 28 days ago
Backend & APIsAuto-check passed
Email Deliverability Audit
growthenginenowoslawski/coldoutboundskills
Diagnostic audit for a running cold email program. An agent skill from growthenginenowoslawski/coldoutboundskills.
753 GitHub stars~3.4k tokensUpdated 4 days ago
Backend & APIsAuto-check passed

Questions about Email

What does Email do?

Send and read email from the iii engine — SMTP send, IMAP read, and real-time IDLE push as a subscribable trigger type. Email is an agent skill from iii-hq/workers. Send and read email from the iii engine — SMTP send, IMAP read, and real-time IDLE push as a subscribable trigger type.

When should I use Email?

Email fits situations like: tasks that involve Transactional email.

How do I install Email in Claude Code?

Run `npx skills add iii-hq/workers --skill email -a claude-code`. Or copy the skill folder (email/skills in iii-hq/workers) into .claude/skills/email in your project. Claude Code loads it when a task matches its description.

How do I install Email in Codex?

Run `npx skills add iii-hq/workers --skill email -a codex`. Or copy the skill folder (email/skills in iii-hq/workers) into .agents/skills/email in your project. Codex loads it when a task matches its description.

Can I use Email in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add iii-hq/workers --skill email -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/email, .gemini/skills/email, .github/skills/email and .opencode/skills/email in your project.

What does Email need to run?

SKILL.md names no scripts, command-line tools or credentials: Email is instructions for the agent only.

Does Email access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Email safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Email use?

Email is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Email use?

About 2.1k tokens (SKILL.md is roughly 8.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Email?

Skills that share tags, products or a category with Email: Stripe Projects (fossasia/eventyay, 1.7k stars), WooCommerce Email Editor Development (woocommerce/woocommerce, 11k stars), Email Best Practices (viclafouch/meme-studio, 110 stars) and React Email (viclafouch/meme-studio, 110 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Email?

iii-hq (a GitHub organization) maintains it in iii-hq/workers, which has 113 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on October 10, 2026.

Source: iii-hq/workers on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Email

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

email

When to Use

Boundaries

Functions

Reactive triggers

How to bind

Delivery semantics

Errors

Files

Compare with similar skills

Similar skills

More from iii-hq/workers

Related

Questions about Email