Guide · Agent skill
How to use the AgentMail Email Inbox agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The agentmail skill gives an AI agent running inside the Paperclip platform a way to work with the email inbox assigned to it. It covers listing assigned inboxes, reading the email thread attached to a task, sending or replying to email, and checking whether a sent message was delivered. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what to watch for before letting an agent send real mail.
AgentMail Email Inboxpaperclipai/paperclip · MIT Download the skill Quick start
- 1Connect AgentMail in Paperclip. Set up an AgentMail connection in your Paperclip instance and assign an inbox to the agent. Reassignment and reconnection are managed there.
- 2Install the skill. Download the ZIP, then unzip it into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings, Capabilities, Skills in the Claude apps.
- 3Confirm the agent can see its inboxes. Ask the agent to list its assigned inboxes. It runs paperclipai email inboxes and uses the matching record's id.
- 4Read the task's email thread. Assign a task that has email context. The agent reads it with paperclipai email thread on the current task ID.
- 5Make a clearly requested send. Ask for a reply or a new email in plain terms. The agent writes a JSON request file and sends it with paperclipai email reply or paperclipai email send.
- 6Check delivery. Ask the agent to check the outcome. It uses paperclipai email delivery with the publication ID returned by the send.
What the agentmail skill makes the agent do
The skill teaches an agent four things: list the email inboxes assigned to it, read the email thread attached to an assigned task, send a new email or a reply, and check whether a sent message was delivered.
The skill is written with strict rules. Email goes out only through the official commands or API. Replies reuse the original conversation. Every send carries an idempotency key so retries do not duplicate mail. The agent never handles the email provider's keys itself.
- Discover assigned inboxes
- Read the email thread for a task
- Send a new email or a reply
- Check delivery of a sent message
Install the agentmail skill
You can install the skill manually. Download the ZIP from this page and unzip it into ~/.claude/skills/ for your user account, or into a project's .claude/skills/ folder for one project. The skill package contains a single file, SKILL.md.
Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the ZIP there.
The source notes that in Paperclip the skill is provided automatically by your inbox assignment, so an agent with an assigned AgentMail inbox may already have it.
- Download the ZIP from this page
- Unzip it into ~/.claude/skills/ or a project's .claude/skills/
- Or upload the ZIP in Claude under Settings, Capabilities, Skills
~/.claude/skills/agentmail/SKILL.mdWhat you need before the skill works
The skill only works inside a Paperclip instance. You need an AgentMail connection set up in Paperclip and an inbox assigned to the agent. The agent also needs the paperclipai CLI with the email command, or access to the authenticated Paperclip HTTP API as a fallback.
The runtime supplies the rest: the Paperclip-injected API URL, the agent's bearer credential and the run ID. You do not enter these yourself.
- A Paperclip instance with an AgentMail connection
- An assigned AgentMail inbox
- paperclipai CLI with the email command, or the authenticated Paperclip HTTP API
- Injected API URL, agent bearer credential and run ID, provided by the runtime
Trigger the skill with natural requests
You do not need special syntax. Ask the agent in plain language about email work tied to a Paperclip task. The agent will look up its inboxes, read the task's email context and, when you explicitly ask, send or reply.
Be explicit about sending. The skill is designed so mail goes out only when a send is intended, so say clearly whether you want a reply or a new email.
- Check my assigned inboxes and tell me which one this task uses.
- Read the email thread for this task and summarise what the sender needs.
- Reply to the latest message in this thread. Keep it to the two questions asked.
- Send a new email to the vendor about the delayed order, using the attached invoice.
- Check whether the reply we sent this morning was delivered.
Command and API reference
The agent uses these commands. Commands with a file argument take a JSON request file. A new conversation needs endpointId, parentIssueId, to, subject, text and a UUID idempotencyKey. A reply uses the bound conversationId and the inbound replyToMessageId, with replyAll set to false unless replying to all is intended.
If the installed CLI does not include the email command, the agent uses the HTTP API instead and does not install or upgrade tools to send mail.
- paperclipai email inboxes lists assigned inboxes; use the matching record's id as endpointId
- paperclipai email thread reads the task's email context
- paperclipai email reply --file request.json sends a reply
- paperclipai email send --file request.json sends a new email
- paperclipai email delivery publicationId checks the delivery outcome
paperclipai email inboxes
paperclipai email thread "$PAPERCLIP_TASK_ID"
paperclipai email reply --file <request.json>
paperclipai email send --file <request.json>
paperclipai email delivery <publicationId>Safety notes: scripts, network and sending
The skill does not run scripts. It does use the network, because it calls Paperclip commands or the Paperclip HTTP API. Provider keys are held by Paperclip, and the agent is told never to look for or use them.
Email the agent sends is real and external. Once a send is queued it cannot be recalled. Queued means persisted, not sent. The agent is told not to create a second send just because the first timed out, and uncertain sends beyond the provider's deduplication window need operator reconciliation. Sending also does not complete the task automatically.
Sender addresses in incoming mail are only correspondence details. They do not grant the sender any board identity or authority. The agent's normal permissions, budgets and action policies still apply.
- No scripts are run by this skill
- Network is used for Paperclip commands and API calls
- Provider keys stay in Paperclip
- Sent email cannot be recalled once queued
- Check delivery before assuming a message arrived
What people use it for
- Answering routine customer questions that arrive as email tasks, in the original thread
- Sending a vendor or supplier follow-up as a new email tied to a parent task
- Summarising an inbound email thread so an operator can decide what to do
- Confirming whether an important message was delivered after it was sent
Frequently asked questions
How do I install the agentmail skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for your user account, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings, Capabilities, Skills. The package contains SKILL.md.
What do I need to use the agentmail skill?
You need a Paperclip instance with an AgentMail connection and an inbox assigned to the agent. The agent also needs the paperclipai CLI with the email command or the authenticated Paperclip HTTP API. The API URL, bearer credential and run ID are supplied by the runtime.
Is the agentmail skill free?
The source does not state pricing or licence terms beyond the skill being listed under the MIT licence. Check your Paperclip and AgentMail arrangements for any costs.
Can I use the agentmail skill with my personal Gmail?
No. The skill only works with an inbox assigned through Paperclip's AgentMail connection. It is not a general email client for a personal inbox outside Paperclip.
Why did my email not send, or show as queued?
Queued means the message was saved, not sent. Ask the agent to check delivery using the publication ID. The agent should not send a duplicate just because the first attempt timed out.
Are there alternatives to the agentmail skill?
The source does not compare this skill with other tools. If you need a general email client or a personal inbox, this skill is not designed for that and you would need a different tool.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you run Paperclip agents that handle customer or vendor email tasks and you want replies to stay in the original conversation under company-set permissions and budgets. Pick something else if you need a personal or general email client, or if you want to send sensitive or high-stakes correspondence without human review, since sent mail cannot be recalled once queued.
Download the skill