API voor links en tijdelijke mail

De API maakt anonieme korte links, geeft hun klikstatistieken terug, wijzigt hun instellingen en verwijdert ze. Verzoeken en antwoorden gebruiken JSON. CORS is ingeschakeld, dus aanroepen werken ook vanuit browsercode. Vanaf Pro beheert hij ook tijdelijke mailboxen: een adres maken, het op mail afvragen en binnengekomen berichten beantwoorden.

LinksTijdelijke e-mailFouten

Basisadres:

https://anonym.es/api/v1

Snel beginnen

Stuur het bestemmingsadres om een korte link te maken:

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

Met een accounttoken zet dezelfde aanroep de link in je dashboard en telt hij mee voor je abonnement:

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

Het antwoord bevat het korte adres, de id van de link en het token dat deze link beheert. Bewaar het token: het is nodig om de link later te lezen of te verwijderen.

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

Velden van het linkobject

Alle endpoints die een link teruggeven gebruiken deze structuur. Tijdstempels zijn ISO 8601 in UTC. De tellers clicks en uniques beslaan de volledige levensduur van de link.

Autorisatie

Geautoriseerde verzoeken dragen het token in de Authorization-header. Als alternatief wordt de header X-API-Key geaccepteerd. Tokens worden nooit in de query string doorgegeven.

Authorization: Bearer YOUR_TOKEN

Een accounttoken begint met anon_. Een linktoken bestaat uit 32 tekens. Het aanmaken van een nieuw accounttoken maakt het vorige ongeldig.

Voorbeeld:

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

Een accounttoken aanmaken in het dashboard

Endpoints

De body van een verzoek kan als application/json of als application/x-www-form-urlencoded worden verzonden. Parameternamen en foutcodes zijn voor alle endpoints gelijk.

Tijdelijke e-mail

De kosten zijn in eenheden van de snelheidslimiet, zie Snelheidslimieten.

Een link maken

POST /api/v1/links

Het minimale verzoek bevat alleen het veld url:

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

Met een accounttoken hoort de link bij het account en telt hij mee voor het abonnement. Zonder token is het een gastlink op de 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"}'

Een geslaagd verzoek geeft status 201 terug met de link, het token en het aantal links dat in de huidige quotaperiode overblijft.

Velden van het antwoord:

Link met een eigen naam

Het korte adres krijgt de naam my-article als die vrij is en aan de regels hieronder voldoet.

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

Naamregels:

• Latijnse letters, cijfers, koppelteken en onderstrepingsteken. Vanaf 5 tekens in het Free-plan en vanaf 3 in betaalde plannen, maximaal 32. Hoofdletters maken geen verschil: Promo en promo zijn dezelfde link.
• Paginanamen, taalcodes en dienstwoorden zijn gereserveerd.
• Merknamen en beledigende woorden worden geweigerd. Namen gaan door een woordenlijst en een automatische controle. Het aantal eigen namen per uur is per plan beperkt.
• Een bezette naam geeft status 409 met vrije alternatieven in suggest.
• Een subdomeinnaam (sub: true, plan Max) is één DNS-label: letters, cijfers en koppeltekens, geen koppelteken aan de randen en geen onderstrepingsteken. Namen als www, mail of ns1 zijn gereserveerd.

Een naam kan worden gecontroleerd voordat de link wordt gemaakt:

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

Velden van het controleantwoord:

Meerdere links tegelijk

Het veld urls accepteert tot 50 adressen, als JSON-array of als tekst met één adres per regel. Elk adres wordt een eigen link met een eigen token, en de overige velden gelden voor alle links. Een eigen naam is in een batch niet beschikbaar.

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

Het antwoord bevat batch: true en een array results met één item per adres, in de verzonden volgorde. Een fout adres levert een item met ok: false en de foutcode op zonder de rest te stoppen.

Extra instellingen

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

Opties die als betaald zijn gemarkeerd worden voor gasten en in het Free-plan genegeerd. Het antwoord geeft de instellingen weer die de link daadwerkelijk heeft gekregen.

Links weergeven

GET /api/v1/links

Vereist een accounttoken. Links worden van nieuw naar oud teruggegeven.

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

Zoeken en het tagfilter kunnen worden gecombineerd:

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

Velden van het antwoord:

Een link vinden via het korte adres

Een link wordt aangesproken met zijn numerieke id (het veld id, bijvoorbeeld 4821), niet met de naam in het korte adres. Als alleen het korte adres bekend is, kan de id worden opgezocht met elk token dat die link beheert:

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

Linkgegevens en statistiek

GET /api/v1/links/{id}

Geeft de instellingen van de link, de status, het aantal bezoeken en het aantal unieke bezoekers over de hele levensduur terug:

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

Met een accounttoken voegt de parameter stats een bezoekrapport toe:

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

Velden van het antwoord: stats

Een link bewerken

PATCH /api/v1/links/{id}

Alleen de verzonden velden veranderen:

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

Een waarde wissen

• password, note en tags: een lege string verwijdert de waarde.
• expires_days en max_hits: null, een lege string of 0 heft de limiet op. self_destruct gaat uit als er geen limiet en geen levensduur meer over is.
• delay: null of een lege string herstelt de standaard van het plan. 0 betekent direct doorsturen.
• url kan niet worden leeggemaakt, en een link met alleen een notitie blijft een notitie nodig hebben.

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

Een link verwijderen

DELETE /api/v1/links/{id}

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

Na het verwijderen is de eigen naam weer vrij. De statistiek wordt samen met de link verwijderd.

Velden van het antwoord:

QR-code

Vraag voor een HTML-img-tag de code op via het korte adres. Dit endpoint heeft geen token nodig: het korte adres zelf is de sleutel, en iedereen die het heeft kan dezelfde code maken.

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

Servercode kan de afbeelding ook per id met een token opvragen, of base64-gecodeerd in JSON ontvangen door qr=true aan de aanroep voor maken of details toe te voegen:

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

Parameters van beide afbeeldingsendpoints:

Het veld qr in JSON-antwoorden:

Accountgegevens

GET /api/v1/me

Vereist een accounttoken. Geeft het plan, de limieten en de resterende quota terug:

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

API voor tijdelijke e-mail

Maak een adres op een van de domeinen van het abonnement, vraag het op nieuwe mail af, lees berichten met hun verificatieresultaat, beantwoord binnengekomen berichten en verwijder het adres als je klaar bent. Je hebt een accounttoken nodig vanaf Pro. De limieten van het abonnement gelden.

Een adres leeft zolang het abonnement toestaat. De cijfers staan in de tabel hieronder. De aanroep extend zet de klok terug. Antwoorden en vrije verzendingen worden per adres per UTC-dag geteld.

De post van een adres wordt versleuteld opgeslagen. De sleutel komt één keer, in het veld key van het antwoord dat het adres aanmaakt. De server bewaart hem niet, dus sla hem zelf op. Stuur hem mee in de header X-Mail-Key wanneer je de lijst opvraagt, een bericht leest, een bijlage ophaalt, verzonden items opvraagt of antwoordt. De server opent de post alleen in het geheugen en alleen voor dat ene antwoord. Zonder de header komen de rijen terug met encrypted = true en zonder inhoud.

Een adres maken

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

Velden van het antwoord: address

De domeinen waarop je abonnement adressen kan aanmaken:

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

Hoeveel adressen het abonnement tegelijk en per uur toestaat en wat er nog over is:

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

Velden van het antwoord: limits

Sleutel kwijt? De aanroep hieronder geeft een nieuwe uit. Post onder de oude sleutel blijft gesloten.

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

De inbox afvragen

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

Velden van het antwoord: messages[]

Een bericht lezen

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

Het volledige bericht voegt deze velden toe aan de lijstvelden:

Een bericht als gelezen of ongelezen markeren:

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

Beantwoorden

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

Het antwoord gaat naar het From-adres van het bericht, in dezelfde thread (In-Reply-To en References), en telt mee voor de antwoorden per dag van het abonnement.

Een bericht verzenden

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

Verzonden

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

Tijdelijke e-mail per abonnement

Fouten

Fouten worden in één JSON-formaat teruggegeven:

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

field bevat de naam van de foutieve parameter, of null wanneer de fout geen specifiek veld betreft. Een bezette naam voegt suggest toe, een betaalde optie upgrade, quota en snelheidslimieten de header Retry-After.

Snelheidslimieten

Elke aanroep kost eenheden en elk plan heeft een budget aan eenheden per minuut (zie Plannen en limieten). Een leesactie kost 1 eenheid, een lijstpagina 2, een QR-code 3, een wijziging 3, een verwijdering 2, een aanmaak 5 plus 1 per adres. Elk antwoord draagt deze headers:

Plannen en limieten

De exacte limieten van elk plan. Links tellen per dag en IP-adres in Free en per maand en account in betaalde plannen. De laatste kolom noemt de instellingen die een plan kan gebruiken.

OpenAPI-specificatie

De volledige technische beschrijving als OpenAPI 3.1-document: https://anonym.es/api/v1/openapi.json

Het bevat schema's en voorbeelden van alle verzoeken en antwoorden, de planlimieten, de naamregels en de foutcodes. Het is geschikt voor Swagger UI, Postman, Insomnia en clientgeneratoren.