⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.0.0

authorizing-api-requests

mailtrap@mailtrap⭐ 11 stars· last commit 3d ago· 1 open issues

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 11 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Mailtrap user skills

Agent skills for Mailtrap end users and builders using LLM-assisted coding. They summarize product flows, API bases and paths, and links to official documentation. They are not a substitute for docs.mailtrap.io or the developer API documentation.

Standard

These skills follow the Agent Skills open standard (Anthropic, Dec 2025). Each skill is a directory containing a SKILL.md with YAML frontmatter (name, description) plus Markdown instructions. Compliant agents read only the frontmatter at startup and pull the body on demand (progressive disclosure), so the same folder works across multiple tools.

The repository is an Agent Plugin: root plugin.json plus mcp.json. A compatible client loads the skills under skills/ and the Mailtrap MCP server from that one package. Native manifests for Claude Code, OpenAI Codex, and Cursor stay for clients that install those formats directly. Windsurf loads the same skills from its skills directory and does not require a plugin manifest.

Install

Plugin

Install this repository as one plugin in any compatible client: Kiro, GitHub Copilot, Cursor, OpenClaw, VS Code, NanoClaw, Hermes Agent, Grok Bot, ChatGPT, and Codex.

Use the repository URL, or a local clone, in that client's plugin install flow (marketplace, Git URL, or local folder):

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

The client reads plugin.json, loads every skill under skills/, and starts the MCP server in mcp.json (npx -y mcp-mailtrap). Start a new session after install.

The plugin does not embed credentials. Set MAILTRAP_API_TOKEN in the client environment before using the MCP server. See Tokens and account_id.

Manual install

If the client does not load Agent Plugins, copy or symlink the skill folders into the skills directory it reads. The examples below assume you cloned this repo to /path/to/mailtrap-skills. After install, restart or reload the agent if it does not pick up new skills.

Cursor

  • Project: .cursor/skills/<skill-name>/
  • User (all projects): ~/.cursor/skills/<skill-name>/
ln -s /path/to/mailtrap-skills/skills/* ~/.cursor/skills/

Claude Code (Anthropic)

  • Project: .claude/skills/<skill-name>/
  • User: ~/.claude/skills/<skill-name>/
ln -s /path/to/mailtrap-skills/skills/* ~/.claude/skills/

Codex CLI (OpenAI)

  • Project: .agents/skills/<skill-name>/
  • User: ~/.agents/skills/<skill-name>/
ln -s /path/to/mailtrap-skills/skills/* ~/.agents/skills/

Gemini CLI (Google)

  • Project: .gemini/skills/<skill-name>/ (also accepts .agents/skills/)
  • User: ~/.gemini/skills/<skill-name>/
ln -s /path/to/mailtrap-skills/skills/* ~/.gemini/skills/

GitHub Copilot

  • Project: .github/skills/<skill-name>/ (also accepts .claude/skills/ and .agents/skills/)
  • User: ~/.copilot/skills/<skill-name>/ (also accepts ~/.agents/skills/)
ln -s /path/to/mailtrap-skills/skills/* ~/.copilot/skills/

Windsurf (Cascade)

  • Project: .windsurf/skills/<skill-name>/
  • User: ~/.codeium/windsurf/skills/<skill-name>/
ln -s /path/to/mailtrap-skills/skills/* ~/.codeium/windsurf/skills/

Other agents

Most other agents that support the Agent Skills standard also accept ~/.agents/skills/ (user scope) and .agents/skills/ (project scope). If your tool uses a different path, point it at this repository's skills/ folder.

Tokens and account_id

Skill examples reference these environment variables instead of literal secrets:

VariableUsed for
MAILTRAP_API_TOKENGeneral API: Email Send (transactional and bulk), Templates, Contacts, Sending Domains
MAILTRAP_SANDBOX_API_TOKENSandbox / Email Testing (separate scope)
MAILTRAP_ACCOUNT_IDPath parameter for account-scoped endpoints (resolve at runtime, do not hardcode)

Full guidance — token scope, where to store tokens, auth header forms, and how to resolve MAILTRAP_ACCOUNT_ID from GET https://mailtrap.io/api/accounts — lives in the authorizing-api-requests skill. Every other skill in this repo points at it instead of duplicating the rules.

Contents

SkillPurpose
authorizing-api-requestsAPI tokens, env vars, auth headers, account_id resolution
sending-emailsLive sending via Email API and SMTP (transactional vs bulk)
testing-with-sandboxEmail Sandbox, Testing API, safe capture in dev/staging
using-email-templatesAccount-scoped templates, Handlebars, API template send
converting-email-templatesConvert templates from SendGrid, Mailgun, Mandrill, Postmark, Brevo, SES to Mailtrap Handlebars
setting-up-sending-domainDomain verification, DNS (add all records), compliance
managing-contactsContacts API, lists, segments, CRM-style sync
receiving-emailsInbound Email: inboxes, webhooks, threads, replies, forwarding rules, agent inboxes

References

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/authorizing-api-requests/SKILL.md7.8 KBupstream ↗
    ---
    name: authorizing-api-requests
    description: >-
      Use when authenticating or authorizing requests to any Mailtrap API
      (Email Send, Email Testing/Sandbox, Templates, Contacts, Sending Domains,
      Suppressions). Use when picking the auth header, choosing token scope,
      storing tokens safely, or resolving the Mailtrap account_id. Use before
      writing or generating any Mailtrap API call.
    ---
    
    # Authorizing Mailtrap API requests
    
    ## Overview
    
    Every Mailtrap API request needs **two things**:
    
    1. An **API token** in an auth header — proves identity and carries the scope.
    2. For account-scoped endpoints (most of them outside of the send hosts), an **`account_id`** in the URL path.
    
    This skill is the single source of truth for both. Other skills (`sending-emails`, `testing-with-sandbox`, `using-email-templates`, `managing-contacts`, `setting-up-sending-domain`) reference these conventions instead of duplicating them.
    
    ## When to use
    
    - Before writing any Mailtrap API call from code, scripts, CI, IaC, or an AI agent
    - Picking which token scope and stream to provision
    - Deciding where to store a token (env, secret manager, CI)
    - Resolving the `account_id` for an account-scoped endpoint
    - Debugging `401 Unauthorized` / `403 Forbidden` responses
    
    ## API tokens
    
    Create tokens at **Settings** > [API Tokens](https://mailtrap.io/api-tokens) with the **smallest scope** that works:
    
    - **Email Sending API** — for `send.api.mailtrap.io` and `bulk.api.mailtrap.io`. Scope per stream (transactional, bulk) when possible.
    - **Email Testing API** — for the Sandbox (`sandbox.api.mailtrap.io`). Always separate from live sending tokens.
    - **Account-level API** — for Contacts, Templates, Sending Domains, Suppressions, and other endpoints under `https://mailtrap.io/api/accounts/{account_id}/...`.
    
    A single token can cover several scopes if the user has the right plan; prefer narrower tokens (one stream / one project / one product surface) so a leak has limited blast radius. Reference: [API tokens documentation](https://docs.mailtrap.io/email-api-smtp/setup/api-tokens.md).
    
    ## Auth headers (two equivalent forms)
    
    Mailtrap accepts either header. Use Bearer in examples — it's the more common HTTP convention and matches most generated SDK code.
    
    | Form                | Header                                       | When to use                                  |
    | ------------------- | -------------------------------------------- | -------------------------------------------- |
    | Bearer (preferred)  | `Authorization: Bearer $MAILTRAP_API_TOKEN`  | Default for new code, SDKs, curl examples    |
    | Api-Token (legacy)  | `Api-Token: $MAILTRAP_API_TOKEN`             | Older clients or where Bearer is awkward     |
    
    Do not send both at the same time. The same value goes in either header.
    
    ## Where to put tokens
    
    - **Local dev:** environment variable, or `.env` file that is in `.gitignore`. Load with `direnv`, `dotenv`, or the framework's built-in mechanism.
    - **CI / build:** the CI provider's encrypted secret store (GitHub Actions secrets, GitLab CI variables, CircleCI contexts). Inject as env vars only.
    - **Production / staging:** a real secret manager (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, Doppler, 1Password, etc.). Rotate on a schedule.
    - **Agent / LLM workflows:** the host agent's secret store. Never paste a token into chat or a prompt.
    
    Hard rules:
    
    - **Never** hardcode a token in source, config, or notebooks.
    - **Never** commit a token. If one lands in git, rotate it; history retention is forever.
    - **Never** pass a token on the command line as a flag — it leaks into shell history, `ps`, and CI logs.
    - **Never** let an LLM echo a literal token back into generated code. Use `$VAR_NAME` shell-var placeholders in all examples so generated code reaches for the env var, not the literal.
    - **Never** mix sandbox and live tokens. A leaked sandbox key must not be able to send real mail.
    
    ## Recommended env var names
    
    These names are used consistently across every other skill in this repo and across the example snippets below.
    
    | Variable                     | Used for                                                                               |
    | ---------------------------- | -------------------------------------------------------------------------------------- |
    | `MAILTRAP_API_TOKEN`         | General API: Email Send (transactional and bulk), Templates, Contacts, Sending Domains, Suppressions |
    | `MAILTRAP_SANDBOX_API_TOKEN` | Sandbox / Email Testing (separate scope)                                               |
    | `MAILTRAP_ACCOUNT_ID`        | Path parameter for account-scoped endpoints                                            |
    
    If your environment uses different names, alias them once at startup so the examples in other skills work unchanged.
    
    ## Resolving `account_id` automatically
    
    `account_id` is the integer prefix on every `https://mailtrap.io/api/accounts/{account_id}/...` endpoint. **Do not hardcode it.** It changes between environments, is different per organization, and is silently wrong when you copy a script to a teammate's account.
    
    Resolve it once per session from the Accounts endpoint, which lists every account the token can access:
    
    ```bash
    curl -s https://mailtrap.io/api/accounts \
      -H "Authorization: Bearer $MAILTRAP_API_TOKEN"
    ```
    
    Response shape (array):
    
    ```json
    [
      {"id": 12345, "name": "My Company", "access_levels": [1000]},
      {"id": 67890, "name": "Client Account", "access_levels": [100]}
    ]
    ```
    
    `access_levels` values:
    
    - `1000` — Account owner
    - `100` — Admin
    - `10` — Viewer (read-only on most endpoints)
    
    One-liner to cache as an env var (pick the right account if the token can see more than one):
    
    ```bash
    export MAILTRAP_ACCOUNT_ID=$(curl -s https://mailtrap.io/api/accounts \
      -H "Authorization: Bearer $MAILTRAP_API_TOKEN" | jq '.[0].id')
    ```
    
    Reference: [Accounts API](https://docs.mailtrap.io/developers/account-management/accounts).
    
    ## Quick reference
    
    ```bash
    # Live sending (no account_id in path)
    curl -X POST https://send.api.mailtrap.io/api/send \
      -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ ... }'
    
    # Account-scoped endpoint
    curl "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/lists" \
      -H "Authorization: Bearer $MAILTRAP_API_TOKEN"
    
    # Sandbox / Testing
    curl -X POST "https://sandbox.api.mailtrap.io/api/send/$MAILTRAP_INBOX_ID" \
      -H "Authorization: Bearer $MAILTRAP_SANDBOX_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ ... }'
    ```
    
    ## Common mistakes
    
    | Mistake                                                       | Fix                                                                                                              |
    | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
    | Hardcoding the token in code, config, or a notebook           | Load from `$MAILTRAP_API_TOKEN` (env, `.env`, CI secret, secret manager); rotate the token if it ever leaked     |
    | Passing the token as a CLI flag (`--token=...`)               | Use env vars; CLI flags leak to shell history, `ps`, and CI logs                                                 |
    | Committing a token, then deleting it in a later commit        | History keeps the value forever — rotate the token immediately, do not just remove the file                      |
    | Pasting a token into chat / prompt / issue                    | Treat chat as public; rotate if it happened                                                                      |
    | Using the live `MAILTRAP_API_TOKEN` against the sandbox host  | Sandbox uses its own scope and `MAILTRAP_SANDBOX_API_TOKEN`; mixing them either fails or sends real mail by accident |
    | Hardcoding `account_id`                                       | Resolve via `GET https://mailtrap.io/api/accounts` once per run an
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/mailtrap-mailtrap-skills-skills-authorizing-api-requests.md

// REPO STATS

11 stars
1 open issues
Last commit: 3d ago