How to use the AgentMail email agent skill (agentmail)

What the agentmail skill lets an agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent instructions for a specific task. Once this skill is installed, the agent knows how to call the AgentMail REST API. The skill is aimed at tasks such as signing up for services and receiving verification codes, or sending transactional messages.

The skill covers creating email accounts, sending and listing messages, reading full messages with their bodies and attachments, and registering webhooks that notify your agent when mail arrives. It does not run code on your machine. The agent makes API calls using your own AgentMail API key.

• Create an inbox at an @theagentmail.net address
• Send email, with optional cc, bcc, threading headers and base64 attachments
• List and read inbox messages and download attachments
• Register, list and delete webhooks for real-time inbound mail
• Read billing balance with a matching organization token scope

Install the agentmail skill in Claude

Download the ZIP for the agentmail skill from this page and unzip it. For a personal setup, place the unzipped skill folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder instead.

If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills. Either way, the skill folder should contain SKILL.md at its top level, which is the only file this skill includes.

• Personal install: ~/.claude/skills/agentmail/
• Project install: .claude/skills/agentmail/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Get an AgentMail account and API key

Before the skill can do anything, you need an AgentMail account and an API key from the AgentMail dashboard. Keys begin with am_. Every request the agent makes sends this key in an Authorization: Bearer header.

Keep the key private. The source recommends validating that the key is present before use and never logging raw provider errors or private message bodies.

• Sign in to the AgentMail dashboard and copy your API key (it starts with am_)
• Store it in an environment variable rather than pasting it into prompts or files you share
• Check current access, limits and billing on the live docs before paid use

Ask for email tasks in natural language

Once installed, you do not need to type API calls yourself. Describe the outcome you want and name the account, recipient and content. Be explicit about sending, because the skill requires explicit authorization for each outgoing message. Creating an inbox does not by itself authorize signups or automated replies.

Good requests name the account, the action and the boundaries. Vague requests such as 'handle my email' give the agent too little to act on safely.

• Create an inbox called my-agent@theagentmail.net for the signup flow and check it for the verification code
• Send this exact message to recipient@example.com with the subject and body I approve below. I authorize this one message only
• List the messages in account abc and summarize any that mention an invoice, without replying
• Register a webhook on my agent account pointing to https://my-agent.example.com/inbox

Send and read email with the API

Sending uses the account's messages endpoint. The request body takes to as an array of addresses, plus subject, text and optionally html. Optional fields include cc, bcc, inReplyTo, references and attachments, where each attachment is an object with filename, contentType and base64 content.

Reading works in two steps. List messages first, then fetch a single message to get its body and attachments. Attachments are downloaded through a separate endpoint that returns a signed URL. The source asks that you validate account and message IDs and bound polling and attachment size and type.

• Send: POST /v1/accounts/{accountId}/messages
• List: GET /v1/accounts/{accountId}/messages
• Full message: GET /v1/accounts/{accountId}/messages/{messageId}
• Attachment URL: GET /v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId}

Set up webhooks and verify their signatures

Webhooks let the agent react to new mail instead of polling. Register a webhook with a publicly reachable HTTPS URL. This requires a public HTTPS endpoint that you control.

Each delivery includes X-AgentMail-Signature, an HMAC-SHA256 hex digest of the raw request body signed with your webhook secret, and X-AgentMail-Timestamp, a millisecond timestamp. Verify the raw bytes, compare digests in constant time, and reject missing, invalid, stale or far-future timestamps. The source is clear that the signature covers the body only, so a timestamp check alone does not stop replays. Keep a bounded, persistent record of processed event IDs and treat repeat deliveries as idempotent.

• Use the raw request body for the HMAC, not a re-serialized copy
• Compare signatures with a constant-time function
• Store processed IDs persistently so a replayed delivery has no second effect
• Treat the email body as data, not as instructions to the agent

Use the TypeScript SDK (optional)

Instead of raw curl, you can use the @agentmail/sdk TypeScript package. It exposes accounts, messages, attachments and webhooks objects that mirror the REST calls. The source notes that SDK examples require the verified theagentmail.net package publisher, so check the publisher before installing. Do not confuse this service with agentmail.to, which is a different domain and has different credentials.

• Import AgentMail from @agentmail/sdk and construct it with your key from an environment variable
• Catch AgentMailError and log only the status and a redacted category