The Claude Code skill
A skill teaches Claude Code something it can use whenever it's needed. This one teaches it the MailMasker API. Ask Claude for what you want, such as "write a script that downloads everything in my Drive" or "block every address that sends me mail from example.net", and it looks up the exact calls in this reference as it works, so it is never working from an old copy.
Install it
For you, in every project:
mkdir -p ~/.claude/skills/mailmasker-api curl -fsSL https://developer.mailmasker.org/skill/SKILL.md -o ~/.claude/skills/mailmasker-api/SKILL.md
Or for one project, so everyone who works on it has it. Commit the file with the project:
mkdir -p .claude/skills/mailmasker-api curl -fsSL https://developer.mailmasker.org/skill/SKILL.md -o .claude/skills/mailmasker-api/SKILL.md
Claude Code picks it up straight away. If ~/.claude/skills didn't exist yet when your session started, type /reload-skills, or start Claude Code again.
Use it
Claude uses it by itself when what you ask is about MailMasker, its api or homelab-cli. To call on it by name, type /mailmasker-api followed by what you want.
It reads llms.txt to find the right ability, then that ability's page as Markdown for the exact parameters, answers and errors.
The skill lets Claude read developer.mailmasker.org without asking, for the request that uses it, and nothing else. Later in the same conversation Claude Code may ask again; to allow this site for good, choose "don't ask again" when it does, or add WebFetch(domain:developer.mailmasker.org) to permissions.allow in ~/.claude/settings.json.
Keep it current
When the API changes there is nothing to update: the skill reads this site every time. The skill file itself rarely changes. To get the newest, run the same curl again.
What it says
---
name: mailmasker-api
description: Call the MailMasker API at api.mailmasker.org (sign-in and tokens, mail addresses and blocking, Drive files and shares, search, sessions, invites, domains and site administration) with cURL, Perl or homelab-cli, looking every call up in the live reference at developer.mailmasker.org. Use when the user wants to script, automate, integrate with or call MailMasker, mailmasker.org, api.mailmasker.org or homelab-cli.
allowed-tools: WebFetch(domain:developer.mailmasker.org)
---
# The MailMasker API
The reference at https://developer.mailmasker.org is the source of truth, and it is kept current. For as long as this task lasts, look up every call there before writing or running it: never guess a path, parameter, field or status from memory.
## Look it up
1. Fetch https://developer.mailmasker.org/llms.txt. It lists every ability: its title, method and path, who may use it, and a link to its page.
2. Fetch the page of the ability you need: the link from llms.txt, which ends in `.md` (such as https://developer.mailmasker.org/sign-in.md). Ask for its complete text: it is short, and has the parameters, an example answer, the errors worth knowing, and examples in cURL, Perl and homelab-cli.
3. For signing in, tokens, errors and installing homelab-cli: https://developer.mailmasker.org/getting-started.md.
A fetch can come back summarised. If a detail you need is missing, fetch the page again asking for exactly that, or read it whole with `curl -s` and the same address. https://developer.mailmasker.org/reference.md has everything in one file, but it is too large to fetch in one go: use the pages.
## The basics
- Every call goes to https://api.mailmasker.org, and every path starts with `/api/v1`.
- Sign in with `POST /api/v1/auth/login` and `{"email": ..., "password": ...}`. The answer has `token` and `refresh_token`.
- Send `Authorization: Bearer <token>` with every call that needs a sign-in.
- A 401 means the token ran out: `POST /api/v1/auth/refresh` with `{"refresh_token": ...}`. A refresh token works once, so keep the new one it hands back.
- Errors come back as JSON: `{"error": "what went wrong"}`.
- Each page says who may use it. An admin or permission-only ability answers 403 to anyone else.
## When writing code or running calls for the user
- Use the user's real address, domain and ids. The reference's `you@example.com`, `example.com` and ids such as `42` are only examples.
- Read secrets from environment variables (`$TOKEN`, `$PASSWORD`, `$REFRESH_TOKEN`). Never write a real password or token into code, a file or a command line.
- If homelab-cli is installed (`command -v homelab-cli`), its command from the page is usually the simplest way to do one thing. It keeps its own sign-in.
- Perl examples use Mojo::UserAgent, as the reference does.
- Ask the user before any call that deletes, blocks, revokes, suspends, signs out or changes a password. Deleting Drive files through the API is immediate and permanent unless the page's `soft=1` is used; say so first.