DEVELOPMENT & DEVOPS · OFFICIAL AGENT SKILLS & PLUGIN

Mailtrap Agent Skills

mailtrap/mailtrap-skills is Mailtrap's official Agent Skills (agentskills.io) and Agent Plugin (agent-plugins.org) package (MIT, plugin.json v1.0.0). It bundles 8 structured SKILL.md playbooks covering API authorization, live transactional/bulk sending, Email Sandbox isolation, template authoring, cross-ESP template conversion, sending domain DNS setup, contacts management, and inbound email handling—and wires the official mcp-mailtrap stdio MCP server (npx -y mcp-mailtrap) via mcp.json.

Explore 8 included skills & install ↓

Included 8 Agent Skills & security conventions

At commit 13969f6, mailtrap/mailtrap-skills organizes Mailtrap's email engineering workflows into 8 progressive-disclosure SKILL.md directories so agents only load full instructions when triggered:

  • authorizing-api-requests: centralizes token scoping (MAILTRAP_API_TOKEN vs. isolated MAILTRAP_SANDBOX_API_TOKEN), Bearer (Authorization: Bearer) vs. legacy Api-Token headers, and runtime MAILTRAP_ACCOUNT_ID discovery from GET https://mailtrap.io/api/accounts rather than hardcoding IDs.
  • sending-emails: separates transactional (send.api.mailtrap.io) vs. bulk promotional (bulk.api.mailtrap.io) streams and /api/batch, recommending official SDKs or HTTP API before falling back to SMTP.
  • testing-with-sandbox: routes dev/staging mail to sandbox.api.mailtrap.io/api/send/{inbox_id} so test emails never reach real recipients.
  • using-email-templates & converting-email-templates: covers template_uuid + template_variables Handlebars payloads plus automated converter.py migration from SendGrid, Mailgun, Mandrill, Postmark, Brevo, and Amazon SES (flagging edge-case syntax for deep review).
  • setting-up-sending-domain: guides complete DNS record provisioning (requiring all records rather than cherry-picking) via UI or Sending Domains API.
  • managing-contacts & receiving-emails: covers Contacts API lists/segments/custom events (kept distinct from sending suppressions) and Inbound Email agent inboxes, threads, and forwarding rules.

Pair with MCP: for tool execution directly inside Claude, Cursor, VS Code, or Codex, pair this skill pack with Mailtrap MCP.

Plugin & manual symlink installation

1. Agent Plugin install (recommended for compatible hosts):

Add the GitHub repository URL in Claude Code, Cursor, VS Code, GitHub Copilot, Codex, Kiro, OpenClaw, or Hermes Agent plugin install flows. The host reads plugin.json, loads all 8 skills under skills/, and connects mcp.json (npx -y mcp-mailtrap):

https://github.com/mailtrap/mailtrap-skills

2. Manual SKILL.md symlink install (Cursor, Claude Code, Codex, Gemini CLI, Copilot, Windsurf):

# Claude Code (~/.claude/skills/) or Cursor (~/.cursor/skills/)
ln -s /path/to/mailtrap-skills/skills/* ~/.claude/skills/

# Cross-agent standard path (Codex CLI & Agent Skills hosts)
ln -s /path/to/mailtrap-skills/skills/* ~/.agents/skills/

After installing, restart or start a new agent session and configure MAILTRAP_API_TOKEN (and MAILTRAP_SANDBOX_API_TOKEN for testing) in your client environment.

Scope, credential & execution boundaries

  • Least-privilege tokens: authorizing-api-requests instructs agents to keep Email Testing (MAILTRAP_SANDBOX_API_TOKEN) strictly separate from live Email Sending tokens (MAILTRAP_API_TOKEN) so staging tests cannot trigger live deliveries.
  • Open-source skill specs vs. hosted APIs: all 8 SKILL.md files, converter Python scripts, and plugin manifests are MIT-licensed; actual email delivery, sandbox capture, and inbound parsing execute against Mailtrap's hosted APIs under your account plan.
  • MCP side-effects: because mcp.json automatically configures npx -y mcp-mailtrap, agents running the combined plugin gain tool access governed by whichever MAILTRAP_API_TOKEN scopes you supply.

Primary sources