Skip to content
Skills Library
Programming · Tool integration

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.

Licence
MIT
Last repository change
07.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
11
Deprecation

No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.

Licence

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

  1. Overview
  2. When to use
  3. API tokens
  4. Auth headers (two equivalent forms)
  5. Where to put tokens
  6. Recommended env var names
  7. Resolving accountid automatically
  8. Quick reference
  9. Common mistakes
Original SKILL.md headings · 137 lines, 1,031 words
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 —…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.