authorizing-api-requests

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 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.

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.

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.

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:

curl -s https://mailtrap.io/api/accounts \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN"

Response shape (array):

[
  {"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):

export MAILTRAP_ACCOUNT_ID=$(curl -s https://mailtrap.io/api/accounts \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" | jq '.[0].id')

Reference: Accounts API.

Quick reference

# 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