API de enlaces y correo temporal

La API crea enlaces cortos anónimos, devuelve sus estadísticas de clics, cambia sus ajustes y los borra. Las peticiones y las respuestas usan JSON. CORS está habilitado, así que las llamadas funcionan también desde código del navegador. En Pro o superior también gestiona buzones temporales: crear una dirección, consultarla en busca de correo y responder a los mensajes recibidos.

EnlacesCorreo temporalErrores

Dirección base:

https://anonym.es/api/v1

Inicio rápido

Para crear un enlace corto, envía la dirección de destino:

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

Con un token de cuenta la misma llamada guarda el enlace en tu panel y lo cuenta en la cuota de tu 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"}'

La respuesta contiene la dirección corta, el id del enlace y el token que gestiona este enlace. Guarda el token: hará falta para leer o borrar el enlace más adelante.

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

Campos del objeto enlace

Todos los endpoints que devuelven un enlace usan esta estructura. Las marcas de tiempo son ISO 8601 en UTC. Los contadores clicks y uniques abarcan toda la vida del enlace.

Autorización

Las peticiones autorizadas llevan el token en la cabecera Authorization. Como alternativa se acepta la cabecera X-API-Key. Los tokens nunca se pasan en la query string.

Authorization: Bearer YOUR_TOKEN

Un token de cuenta empieza por anon_. Un token de enlace consta de 32 caracteres. Generar un nuevo token de cuenta invalida el anterior.

Ejemplo:

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

Generar un token de cuenta en el panel

Endpoints

El cuerpo de la petición puede enviarse como application/json o como application/x-www-form-urlencoded. Los nombres de los parámetros y los códigos de error son idénticos en todos los endpoints.

Correo temporal

El coste se indica en unidades del límite de ritmo, véase Límites de ritmo.

Crear un enlace

POST /api/v1/links

La petición mínima contiene solo el campo url:

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

Con un token de cuenta el enlace pertenece a la cuenta y se cuenta en la cuota de su plan. Sin token es un enlace de invitado en la cuota de la 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"}'

Una petición correcta devuelve el estado 201 junto con el enlace, su token y el número de enlaces que quedan en el periodo de cuota actual.

Campos de la respuesta:

Enlace con nombre propio

La dirección corta recibe el nombre my-article si está libre y cumple las reglas siguientes.

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

Reglas de los nombres:

• Letras latinas, dígitos, guion y guion bajo. Desde 5 caracteres en el plan Free y desde 3 en los planes de pago, hasta 32. No se distinguen mayúsculas: Promo y promo son el mismo enlace.
• Los nombres de páginas, los códigos de idioma y las palabras de servicio están reservados.
• Se rechazan los nombres de marcas y las palabras ofensivas. Los nombres pasan por una lista de palabras y una revisión automática. El número de nombres propios por hora está limitado según el plan.
• Un nombre ocupado devuelve el estado 409 con alternativas libres en suggest.
• Un nombre de subdominio (sub: true, plan Max) es una etiqueta DNS: letras, dígitos y guiones, sin guion en los extremos ni guion bajo. Nombres como www, mail o ns1 están reservados.

Un nombre puede comprobarse antes de crear el enlace:

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

Campos de la respuesta de comprobación:

Varios enlaces a la vez

El campo urls acepta hasta 50 direcciones, como array JSON o como texto con una dirección por línea. Cada dirección se convierte en su propio enlace con su propio token, y los demás campos se aplican a todos. El nombre propio no está disponible en un lote.

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

La respuesta contiene batch: true y un array results con una entrada por dirección, en el orden enviado. Una dirección defectuosa produce una entrada con ok: false y el código de error sin detener el resto.

Ajustes adicionales

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

Las opciones marcadas como de pago se ignoran para invitados y en el plan Free. La respuesta refleja los ajustes que el enlace recibió realmente.

Listar enlaces

GET /api/v1/links

Requiere un token de cuenta. Los enlaces se devuelven de más nuevo a más antiguo.

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

La búsqueda y el filtro por etiqueta pueden combinarse:

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

Campos de la respuesta:

Buscar un enlace por su dirección corta

Un enlace se identifica por su id numérico (el campo id, por ejemplo 4821), no por el nombre de la dirección corta. Cuando solo se conoce la dirección corta, el id puede obtenerse con cualquier token que gestione ese enlace:

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

Detalles del enlace y estadísticas

GET /api/v1/links/{id}

Devuelve los ajustes del enlace, su estado, el número de visitas y el número de visitantes únicos durante toda su vida:

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

Con un token de cuenta, el parámetro stats añade un informe de visitas:

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

Campos de la respuesta: stats

Editar un enlace

PATCH /api/v1/links/{id}

Solo cambian los campos enviados:

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

Vaciar un valor

• password, note y tags: una cadena vacía elimina el valor.
• expires_days y max_hits: null, una cadena vacía o 0 quitan el límite. self_destruct se desactiva cuando no queda ni límite ni duración.
• delay: null o una cadena vacía restauran el valor por defecto del plan. 0 significa redirección inmediata.
• url no puede vaciarse, y un enlace de solo nota sigue necesitando una nota.

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

Borrar un enlace

DELETE /api/v1/links/{id}

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

Tras el borrado, el nombre propio vuelve a quedar libre. Las estadísticas se borran junto con el enlace.

Campos de la respuesta:

Código QR

Para una etiqueta img de HTML, solicita el código por la dirección corta. Este endpoint no necesita token: la propia dirección corta es la clave, y cualquiera que la tenga puede generar el mismo código.

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

El código del lado del servidor también puede solicitar la imagen por id con un token, o recibirla en JSON codificada en base64 añadiendo qr=true a la llamada de creación o de detalles:

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

Parámetros de ambos endpoints de imagen:

El miembro qr en las respuestas JSON:

Detalles de la cuenta

GET /api/v1/me

Requiere un token de cuenta. Devuelve el plan, sus límites y la cuota restante:

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

API de correo temporal

Crea una dirección en uno de los dominios del plan, consúltala en busca de correo, lee los mensajes con sus resultados de autenticación, responde a los mensajes recibidos y elimina la dirección cuando termines. Hace falta un token de cuenta en Pro o superior. Se aplican los límites del plan.

Una dirección vive lo que permite el plan. Las cifras están en la tabla de más abajo. La llamada extend reinicia el reloj. Las respuestas y los envíos libres se cuentan por dirección y día UTC.

El correo de una dirección se guarda cifrado. La clave llega una sola vez, en el campo key de la respuesta que crea la dirección. El servidor no la conserva, así que guárdala tú. Envíala en la cabecera X-Mail-Key cuando pidas la lista, leas un mensaje, descargues un adjunto, pidas los enviados o respondas. El servidor abre el correo en memoria y solo para esa respuesta. Sin la cabecera, las filas vuelven con encrypted = true y sin contenido.

Crear una dirección

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

Campos de la respuesta: address

Los dominios en los que tu plan puede crear direcciones:

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

Cuántas direcciones da el plan a la vez y por hora, y cuántas quedan:

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

Campos de la respuesta: limits

¿Has perdido la clave? La llamada de abajo emite una nueva. El correo sellado con la clave anterior sigue cerrado.

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

Consultar la bandeja

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

Campos de la respuesta: messages[]

Leer un mensaje

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

El mensaje completo añade estos campos a los de la lista:

Marcar un mensaje como leído o no leído:

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

Responder

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

La respuesta va a la dirección From del mensaje, en el mismo hilo (In-Reply-To y References), y cuenta para las respuestas diarias del plan.

Enviar un mensaje

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

Enviados

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

Correo temporal por plan

Errores

Los errores se devuelven en un único formato JSON:

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

field contiene el nombre del parámetro incorrecto, o null cuando el error no se refiere a un campo concreto. Un nombre ocupado añade suggest, una opción de pago añade upgrade, las cuotas y los límites de ritmo añaden la cabecera Retry-After.

Límites de ritmo

Cada llamada cuesta unidades y cada plan dispone de un presupuesto de unidades por minuto (véase Planes y límites). Una lectura cuesta 1 unidad, una página de lista 2, un código QR 3, una edición 3, un borrado 2, una creación 5 más 1 por dirección. Cada respuesta lleva estas cabeceras:

Planes y límites

Los límites exactos de cada plan. Los enlaces se cuentan por día y dirección IP en Free, y por mes y cuenta en los planes de pago. La última columna enumera los ajustes que puede usar cada plan.

Especificación OpenAPI

La descripción técnica completa como documento OpenAPI 3.1: https://anonym.es/api/v1/openapi.json

Contiene esquemas y ejemplos de todas las peticiones y respuestas, los límites de los planes, las reglas de los nombres y los códigos de error. Sirve para Swagger UI, Postman, Insomnia y generadores de clientes.