authorizing-api-requests
/authorizing-api-requests
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.
- Author
- mailtrap ↗
- Repository
- mailtrap-skills ↗
- Licence
- MIT
- Last repository change
- 07.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 11
No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Original author 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.
How it works
- Overview
- When to use
- API tokens
- Auth headers (two equivalent forms)
- Where to put tokens
- Recommended env var names
- Resolving accountid automatically
- Quick reference
- Common mistakes
SKILL.md preview
---
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 and pass through `$MAILTRAP_ACCOUNT_ID` |
| Picking the wrong account when the token can see several | Filter the `GET /api/accounts` response by `name` or `access_levels` (1000 = owner) instead of `.[0]` |
| Sending both `Authorization` and `Api-Token` headers | Pick one (Bearer for new code); duplicating them is unnecessary and confuses some intermediaries |
| Using a viewer-scoped token for writes | Check `access_levels`; writes need 100 (admin) or 1000 (owner) for the relevant account |
Versions
The database has no other skills named authorizing-api-requests.
Database snapshot: 13.11.2026 · package version eaec8bf0daf7 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100mailtrap-email-integration
Guides agents through integrating transactional email sending via Mailtrap's Email API, including sandbox testing, domain verification, and API authentication. Use when implementing email-sending features, debugging delivery issues, or setting up safe dev/staging email testing. - 100mailtrap-email-integration
Guides agents through integrating transactional email sending via Mailtrap's Email API, including sandbox testing, domain verification, and API authentication. Use when implementing email-sending features, debugging delivery issues, or setting up safe dev/staging email testing. - 100sending-emails
Use when integrating, configuring, or troubleshooting Mailtrap live email sending (Email API or SMTP). Use when wiring outbound mail from an application or choosing how to send. - 100mailtrap-webhooks
Receive and verify Mailtrap webhooks. Use when setting up Mailtrap Email API/SMTP webhook handlers, debugging Mailtrap-Signature verification (HMAC-SHA256 hex over the raw body), handling batched JSON or JSON Lines payloads, or handling sending events like delivery, bounce, soft… - 100testing-with-sandbox
Use when capturing outbound email in development or staging without delivering to real recipients, inspecting HTML or headers, running spam or structure checks, or automating tests against a fake inbox. Use when testing outgoing mail from an app without committing to a… - 100malumail-send
Send transactional email through the MaluMail API (api.malumail.com) and integrate MaluMail sending into an application. Use when an app needs to send email programmatically — welcome/verification/receipt/notification/password-reset messages, alerts, or any outbound mail —…