Link and Temp Mail API

The API creates anonymous short links, returns their click statistics, changes their settings and deletes them. Requests and responses use JSON. CORS is enabled, so calls work from browser code as well. On Pro and up it also runs temporary inboxes: create an address, poll it for mail and reply to incoming messages.

LinksTemp MailErrors

Base address:

https://anonym.es/api/v1

Quick start

To create a short link, send the destination address:

curl -X POST https://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

With an account token the same call puts the link into your dashboard and counts it against your plan:

curl -X POST https://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

The response contains the short address, the link id and the token that manages this link. Keep the token: it is needed to read or delete the link later.

{
  "ok": true,
  "link": {
    "id": 4821,
    "short": "https://anonym.es/k7m2q",
    "url": "https://example.com/article",
    "status": "active",
    "password": false,
    "created_at": "2026-09-05T14:02:11Z",
    "expires_at": null,
    "max_hits": null,
    "self_destruct": false,
    "delay": null,
    "no_countdown": false,
    "adult": false,
    "note": null,
    "tags": [],
    "clicks": 0,
    "uniques": 0
  },
  "token": "3f9c1b7e2d4a4c0e9b8f7a6d5c4b3a21",
  "left": 4
}

Fields of the link object

All endpoints that return a link use this structure. Timestamps are ISO 8601 in UTC. The clicks and uniques counters cover the entire lifetime of the link.

Authorization

Authorized requests carry the token in the Authorization header. The X-API-Key header is accepted as an alternative. Tokens are never passed in the query string.

Authorization: Bearer YOUR_TOKEN

An account token starts with anon_. A link token consists of 32 characters. Generating a new account token invalidates the previous one.

Example:

curl https://anonym.es/api/v1/me \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Generate an account token in the dashboard

Endpoints

Request bodies may be sent as application/json or as application/x-www-form-urlencoded. Parameter names and error codes are identical across all endpoints.

Temp Mail

The cost is given in rate-limit units, see Rate limits.

Creating a link

POST /api/v1/links

The minimal request contains only the url field:

curl -X POST https://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

With an account token the link belongs to the account and counts against its plan. Without a token it is a guest link on the IP quota:

curl -X POST https://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

A successful request returns status 201 together with the link, its token and the number of links left in the current quota period.

Fields of the response:

Link with a custom name

The short address gets the name my-article if it is free and meets the rules below.

curl -X POST https://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","name":"my-article"}'

Name rules:

• Latin letters, digits, hyphen and underscore. From 5 characters on the Free plan and from 3 on paid plans, up to 32. Case does not matter: Promo and promo are the same link.
• Page names, language codes and service words are reserved.
• Brand names and offensive words are refused. Names pass a word list and an automated review. The number of custom names per hour is limited by plan.
• A taken name returns status 409 with free alternatives in suggest.
• A subdomain name (sub: true, Max plan) is one DNS label: letters, digits and hyphens, no hyphen at either end, no underscore. Names such as www, mail or ns1 are reserved.

A name can be checked before the link is created:

curl "https://anonym.es/api/v1/names/check?name=my-article"

Fields of the check response:

Several links at once

The urls field accepts up to 50 addresses, as a JSON array or as text with one address per line. Each address becomes its own link with its own token, and the other fields apply to all of them. A custom name is not available in a batch.

curl -X POST https://anonym.es/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/a","https://example.com/b","https://example.com/c"]}'

The response contains batch: true and a results array with one entry per address, in the order sent. A faulty address produces an entry with ok: false and the error code without stopping the rest.

Additional settings

curl -X POST https://anonym.es/api/v1/links \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "name": "my-article",
    "expires_days": 30,
    "max_hits": 1000,
    "self_destruct": true,
    "password": "secret",
    "note": "Available until the end of the month",
    "delay": 5,
    "tags": "blog,promo",
    "qr": true,
    "qr_size": 300,
    "qr_format": "png"
  }'

Options marked as paid are ignored for guests and on the Free plan. The response reflects the settings the link actually received.

Listing links

GET /api/v1/links

Requires an account token. Links are returned newest first.

curl "https://anonym.es/api/v1/links?page=1&per=50" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Search and the tag filter can be combined:

curl "https://anonym.es/api/v1/links?q=example&tag=promo" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Fields of the response:

Finding a link by its short address

A link is addressed by its numeric id (the id field, for example 4821), not by the name in the short address. When only the short address is known, the id can be looked up with any token that manages the link:

curl --get https://anonym.es/api/v1/links/lookup \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "short=https://anonym.es/k7m2q"

Link details and statistics

GET /api/v1/links/{id}

Returns the settings of the link, its status, the number of visits and the number of unique visitors for its whole life:

curl https://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer YOUR_TOKEN"

With an account token, a visits report can be added with the stats parameter:

curl "https://anonym.es/api/v1/links/4821?stats=day" \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Fields of the response: stats

Editing a link

PATCH /api/v1/links/{id}

Only the fields sent change:

curl -X PATCH https://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"max_hits": 2000, "delay": 3, "tags": "blog,updated"}'

Clearing a value

• password, note and tags: an empty string removes the value.
• expires_days and max_hits: null, an empty string or 0 removes the limit. self_destruct turns off when neither a cap nor a lifetime is left.
• delay: null or an empty string restores the plan default. 0 means an instant redirect.
• url cannot be emptied, and a note-only link keeps needing a note.

curl -X PATCH https://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "", "note": "", "expires_days": null, "max_hits": null, "delay": 0}'

Deleting a link

DELETE /api/v1/links/{id}

curl -X DELETE https://anonym.es/api/v1/links/4821 \
  -H "Authorization: Bearer YOUR_TOKEN"

After deletion the custom name becomes free again. The statistics are deleted together with the link.

Fields of the response:

QR code

For an HTML img tag, request the code by the short address. This endpoint needs no token: the short address itself is the key, and anyone who has it can generate the same code.

<img
  src="https://anonym.es/api/v1/qr?short=https%3A%2F%2Fanonym.es%2Fk7m2q&qr_size=400"
  alt="QR code"
>

Server-side code can also request the image by id with a token, or receive it base64-encoded in JSON by adding qr=true to the create or details call:

curl "https://anonym.es/api/v1/links/4821/qr?qr_size=400&qr_format=svg" \
  -H "Authorization: Bearer YOUR_TOKEN" -o qr.svg

Parameters of both image endpoints:

The qr member in JSON responses:

Account details

GET /api/v1/me

Requires an account token. Returns the plan, its limits and the remaining quota:

curl https://anonym.es/api/v1/me \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Temp Mail API

Create an address on one of the plan's domains, poll it for mail, read messages with their authentication results, reply to incoming messages and delete the address when done. You need an account token on Pro or higher. The plan's limits apply.

An address lives as long as the plan allows. The table below has the numbers. Calling extend resets that clock. Replies and free sends are counted per address per UTC day.

Mail of an address is stored encrypted. The key comes once, in the key field of the answer that creates the address. The server does not keep it, so store it yourself. Send it in the X-Mail-Key header when you list messages, read one, download an attachment, list sent items or reply. The server opens the mail in memory and only for that one answer. Without the header the rows come back with encrypted = true and no content.

Create an address

curl -X POST https://anonym.es/api/v1/mail/addresses \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"quiet-heron-41","domain":"anon.skin"}'

Fields of the response: address

The domains your plan can create addresses on:

curl https://anonym.es/api/v1/mail/domains \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

How many addresses the plan gives at once and in an hour, and what is left:

curl https://anonym.es/api/v1/mail/limits \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Fields of the response: limits

Lost the key? The call below issues a new one. Mail sealed with the old key stays closed.

curl -X POST https://anonym.es/api/v1/mail/addresses/17/key \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN"

Poll the inbox

curl https://anonym.es/api/v1/mail/addresses/17/messages \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "X-Mail-Key: ADDRESS_KEY"

Fields of the response: messages[]

Read a message

curl https://anonym.es/api/v1/mail/addresses/17/messages/2 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "X-Mail-Key: ADDRESS_KEY"

The full message adds these fields to the list fields:

Mark a message read or unread:

curl -X PATCH https://anonym.es/api/v1/mail/addresses/17/messages/2 \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read": false}'

Reply

curl -X POST https://anonym.es/api/v1/mail/addresses/17/messages/2/reply \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "X-Mail-Key: ADDRESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Confirmed, thanks."}'

The reply goes to the From address of the message, threaded with In-Reply-To and References, and counts against the plan's replies per day.

Send a message

curl -X POST https://anonym.es/api/v1/mail/addresses/17/send \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"[email protected]","subject":"Hello","text":"Sent from a temporary address."}'

Sent items

curl https://anonym.es/api/v1/mail/addresses/17/sent \
  -H "Authorization: Bearer anon_YOUR_ACCOUNT_TOKEN" \
  -H "X-Mail-Key: ADDRESS_KEY"

Temp Mail by plan

Errors

Errors are returned in a single JSON format:

{
  "ok": false,
  "error": "taken",
  "message": "This name is already taken.",
  "field": "name",
  "suggest": ["my-article-26", "my-my-article", "my-article-link"]
}

field contains the name of the faulty parameter, or null when the error does not concern a specific field. A taken name adds suggest, a paid option adds upgrade, quotas and rate limits add the Retry-After header.

Rate limits

Each call costs units, and each plan has a budget of units per minute (see Plans and limits). A read costs 1 unit, a list page 2, a QR code 3, an edit 3, a deletion 2, a creation 5 plus 1 per address. Every response carries these headers:

Plans and limits

The exact limits of each plan. Links are counted per day and IP address on Free, per month and account on paid plans. The last column lists the settings a plan can use.

OpenAPI specification

The complete technical description as an OpenAPI 3.1 document: https://anonym.es/api/v1/openapi.json

It contains schemas and examples of every request and response, the plan limits, the name rules and the error codes. It suits Swagger UI, Postman, Insomnia and client generators.