API ссылок и временной почты

API создаёт анонимные короткие ссылки, возвращает статистику переходов, изменяет настройки и удаляет ссылки. Запросы и ответы передаются в формате JSON. CORS включён, поэтому вызовы работают и из кода в браузере. На тарифах Pro и выше он же управляет временной почтой: создать адрес, опросить его на новые письма, ответить на входящие письма.

СсылкиВременная почтаОшибки

Базовый адрес:

https://anonym.es/api/v1

Быстрый старт

Чтобы создать короткую ссылку, отправьте адрес назначения:

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

С токеном аккаунта тот же вызов помещает ссылку в ваш кабинет и учитывает её в квоте тарифа:

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"}'

Ответ содержит короткий адрес, идентификатор ссылки и токен управления этой ссылкой. Сохраните токен: он понадобится, чтобы позже прочитать или удалить ссылку.

{
  "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
}

Поля объекта ссылки

Все эндпоинты, возвращающие ссылку, используют эту структуру. Время указано в формате ISO 8601 в UTC. Счётчики clicks и uniques охватывают весь срок жизни ссылки.

Авторизация

Авторизованные запросы передают токен в заголовке Authorization. Как альтернатива принимается заголовок X-API-Key. В строке запроса токены не передаются.

Authorization: Bearer YOUR_TOKEN

Токен аккаунта начинается с anon_. Токен ссылки состоит из 32 символов. Создание нового токена аккаунта отменяет предыдущий.

Пример:

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

Создать токен аккаунта в личном кабинете

Эндпоинты

Тело запроса передаётся как application/json или application/x-www-form-urlencoded. Имена параметров и коды ошибок одинаковы для всех эндпоинтов.

Временная почта

Стоимость указана в единицах лимита запросов, см. раздел «Лимиты запросов».

Создание ссылки

POST /api/v1/links

Минимальный запрос содержит только поле url:

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

С токеном аккаунта ссылка принадлежит аккаунту и учитывается в квоте тарифа. Без токена это гостевая ссылка в квоте IP-адреса:

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"}'

Успешный запрос возвращает статус 201 вместе со ссылкой, её токеном и числом ссылок, оставшихся в текущем периоде квоты.

Поля ответа:

Ссылка с собственным именем

Короткий адрес получит имя my-article, если оно свободно и соответствует правилам ниже.

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

Правила имён:

• Латинские буквы, цифры, дефис и подчёркивание. От 5 символов на тарифе Free и от 3 на платных тарифах, не более 32. Регистр не учитывается: Promo и promo считаются одной ссылкой.
• Имена страниц сайта, коды языков и служебные слова зарезервированы.
• Названия брендов и оскорбительные слова отклоняются. Имена проходят проверку по списку слов и автоматическую модерацию. Число собственных имён в час ограничено тарифом.
• Занятое имя возвращает статус 409 со свободными вариантами в поле suggest.
• Имя сабдомена (sub: true, тариф Max) состоит из одной DNS-метки: буквы, цифры и дефисы, без дефиса по краям и без подчёркивания. Имена вида www, mail или ns1 зарезервированы.

Имя можно проверить до создания ссылки:

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

Поля ответа проверки:

Несколько ссылок за один запрос

Поле urls принимает до 50 адресов в виде JSON-массива или текста с одним адресом в строке. Каждый адрес становится отдельной ссылкой со своим токеном, а остальные поля применяются ко всем. Собственное имя в пакете недоступно.

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"]}'

Ответ содержит batch: true и массив results с записью на каждый адрес в порядке отправки. Ошибочный адрес даёт запись с ok: false и кодом ошибки, не прерывая остальные.

Дополнительные настройки

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"
  }'

Опции, отмеченные как платные, игнорируются для гостей и на тарифе Free. Ответ отражает настройки, которые ссылка получила фактически.

Список ссылок

GET /api/v1/links

Требуется токен аккаунта. Ссылки возвращаются от новых к старым.

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

Поиск и фильтр по тегу можно сочетать:

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

Поля ответа:

Поиск ссылки по короткому адресу

Ссылка адресуется числовым идентификатором (поле id, например 4821), а не именем из короткого адреса. Если известен только короткий адрес, идентификатор можно получить любым токеном, который управляет этой ссылкой:

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

Сведения о ссылке и статистика

GET /api/v1/links/{id}

Возвращает настройки ссылки, её состояние, число переходов и число уникальных посетителей за всё время:

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

С токеном аккаунта параметр stats добавляет отчёт о переходах:

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

Поля ответа: stats

Изменение ссылки

PATCH /api/v1/links/{id}

Изменяются только переданные поля:

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"}'

Сброс значения

• password, note и tags: пустая строка удаляет значение.
• expires_days и max_hits: null, пустая строка или 0 снимают ограничение. self_destruct отключается, когда не остаётся ни лимита, ни срока.
• delay: null или пустая строка возвращают значение тарифа по умолчанию. 0 означает мгновенный переход.
• url нельзя сделать пустым, а ссылке-заметке по-прежнему нужна заметка.

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}'

Удаление ссылки

DELETE /api/v1/links/{id}

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

После удаления собственное имя снова становится свободным. Статистика удаляется вместе со ссылкой.

Поля ответа:

QR-код

Для HTML-тега img запрашивайте код по короткому адресу. Этот эндпоинт не требует токена: ключом служит сам короткий адрес, и любой, кто его знает, может получить такой же код.

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

Серверный код может также запросить изображение по идентификатору с токеном или получить его в JSON в кодировке base64, добавив qr=true к запросу создания или сведений:

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

Параметры обоих эндпоинтов изображения:

Поле qr в ответах JSON:

Сведения об аккаунте

GET /api/v1/me

Требуется токен аккаунта. Возвращает тариф, его ограничения и остаток квоты:

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

API временной почты

Создайте адрес на одном из доменов тарифа, опрашивайте его на новые письма, читайте сообщения с результатами аутентификации, отвечайте на входящие письма и удаляйте адрес, когда он больше не нужен. Нужен токен аккаунта на тарифе Pro и выше. Действуют лимиты тарифа.

Адрес живёт столько, сколько позволяет тариф. Сроки - в таблице ниже. Вызов extend сбрасывает таймер. Ответы и свободные отправки считаются на адрес за сутки по UTC.

Письма адреса хранятся зашифрованными. Ключ приходит один раз, в поле key ответа на создание адреса. На сервере он не хранится, поэтому сохраните его у себя. Присылайте ключ заголовком X-Mail-Key, когда запрашиваете список, читаете письмо, скачиваете вложение, смотрите отправленные или отвечаете. Сервер открывает письма в памяти и только на время этого ответа. Без заголовка строки приходят с encrypted = true и без содержимого.

Создать адрес

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"}'

Поля ответа: address

Домены, на которых ваш тариф может создавать адреса:

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

Сколько адресов тариф даёт одновременно и за час и сколько ещё осталось:

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

Поля ответа: limits

Потеряли ключ? Вызов ниже выдаст новый. Письма под старым ключом останутся закрытыми.

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

Опросить входящие

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

Поля ответа: messages[]

Прочитать письмо

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

Полное письмо добавляет к полям списка следующие:

Пометить письмо прочитанным или непрочитанным:

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}'

Ответить

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."}'

Ответ уходит на адрес From письма, в той же цепочке (In-Reply-To и References), и списывается из ответов тарифа за сутки.

Отправить письмо

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."}'

Отправленные

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

Временная почта по тарифам

Ошибки

Ошибки возвращаются в едином JSON-формате:

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

field содержит имя некорректного параметра или null, если ошибка не относится к конкретному полю. Занятое имя добавляет suggest, платная опция добавляет upgrade, квоты и лимиты частоты добавляют заголовок Retry-After.

Лимиты частоты

Каждый вызов стоит единицы, а у каждого тарифа есть бюджет единиц в минуту (см. «Тарифы и ограничения»). Чтение стоит 1 единицу, страница списка 2, QR-код 3, редактирование 3, удаление 2, создание 5 плюс 1 за каждый адрес. Каждый ответ содержит заголовки:

Тарифы и ограничения

Точные ограничения каждого тарифа. Ссылки считаются за сутки на IP-адрес на Free и за месяц на аккаунт на платных тарифах. Последний столбец перечисляет настройки, доступные тарифу.

Спецификация OpenAPI

Полное техническое описание в виде документа OpenAPI 3.1: https://anonym.es/api/v1/openapi.json

Документ содержит схемы и примеры всех запросов и ответов, ограничения тарифов, правила имён и коды ошибок. Подходит для Swagger UI, Postman, Insomnia и генераторов клиентов.