Agent skills

mails.ai has three agent skills: instructions an AI agent loads when a task involves email through mails.ai. Each skill is a folder in the Agent Skills format: SKILL.md, which the agent loads when it uses the skill; references/, which it reads when it needs them; and examples/, runnable TypeScript and Python.

The skills

Email for an agent with mails.ai

The mails skill. Give an AI agent its own email address and send, receive and reply to email through mails.ai. Use when a task needs an agent to send transactional email, wait for and read replies, keep a conversation in one thread, or test an email flow without contacting a real person. Covers the REST API, the @mailsai/sdk TypeScript SDK, the mailsai Python SDK and the mails.ai MCP server.

8 reference pages: api.md, cli.md, errors-and-retries.md, mcp.md, receiving.md, sdk-python.md, sdk-typescript.md, testing.md. 7 runnable examples: 3 in TypeScript and 4 in Python. Version 0.1.0, MIT license.

Act on inbound email safely

The agent-inbox skill. Let an AI agent act on email it receives through mails.ai without being steered by the people who write to it. Use when an agent reads incoming email and then replies, calls tools or changes anything because of it, when setting up a webhook or a poller for inbound mail, or when verifying a mails.ai webhook signature. Covers five levels of protection (sender allowlist, domain allowlist, injection-score threshold, sandboxed reply tools, human approval through drafts), webhook signature checks, and replay and flood protection.

5 reference pages: event-fields.md, injection-score.md, replay-and-flood.md, security-levels.md, webhooks.md. 13 runnable examples: 6 in TypeScript and 7 in Python. Version 0.1.0, MIT license.

Email that lands and follows the rules

The email-best-practices skill. Send transactional email through mails.ai that reaches the inbox and stays within the rules. Use when setting up a custom sending domain (SPF, DKIM, DMARC), handling bounces, spam complaints, unsubscribes and suppressed addresses, deciding whether a message is transactional or would be refused as cold outreach, or checking what CAN-SPAM, GDPR and CASL require of email an agent sends.

4 reference pages: bounces-and-complaints.md, compliance.md, dns-authentication.md, what-mails-ai-refuses.md. 5 runnable examples: 2 in TypeScript and 3 in Python. Version 0.1.0, MIT license.

Install

Install them with the skills command:

npx skills add mailsai/skills

Add --skill mails to install one skill, -a claude-code to pick the agent, and -g to install for your user instead of the current project.

Or copy the skill folders by hand. Claude Code reads skills from ~/.claude/skills/, or from .claude/skills/ inside a project to install them for that project only. Other agents read skills from their own folders; see their documentation.

What the examples need

• A mails.ai API key in MAILS_API_KEY. Start with a test key (mk_test_…): nothing is delivered and nothing is billed.
• TypeScript: Node.js 18 or newer, npm install @mailsai/sdk, and npx tsx <file> to run.
• Python: Python 3.10 or newer and pip install mailsai. rest.py in each skill’s examples/ calls any endpoint with only the standard library, for code where the SDK is not installed.

The skills come with a check that covers their frontmatter against the Agent Skills rules, every link, every API path against the API’s OpenAPI document, and every example against the SDKs as they are in the mails.ai repository: type-checked, and run against a local stand-in for the API.

As an agent plugin

The skills folder is also an Agent Plugin: plugin.json describes it, skills/ holds the skills, and mcp.json registers the hosted mails.ai MCP server at https://api.mails.ai/mcp.

A client that installs the plugin connects to the hosted server and asks you to sign in to mails.ai and approve access, so no key goes in any file.

Next steps