Link- und Temp-Mail-API

Die API legt anonyme Kurzlinks an, liefert ihre Klickstatistik, ändert ihre Einstellungen und löscht sie. Anfragen und Antworten verwenden JSON. CORS ist aktiviert, Aufrufe funktionieren daher auch aus Browser-Code. Ab Pro steuert sie auch temporäre Postfächer: eine Adresse anlegen, sie auf Mail abfragen, auf eingehende Mails antworten.

LinksTemporäre E-MailFehler

Basisadresse:

https://anonym.es/api/v1

Schnellstart

Um einen Kurzlink anzulegen, senden Sie die Zieladresse:

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

Mit einem Kontotoken legt derselbe Aufruf den Link in Ihrem Dashboard ab und zählt ihn auf Ihren Tarif:

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

Die Antwort enthält die Kurzadresse, die Link-ID und das Token, das diesen Link verwaltet. Bewahren Sie das Token auf: Es wird gebraucht, um den Link später zu lesen oder zu löschen.

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

Felder des Link-Objekts

Alle Endpunkte, die einen Link zurückgeben, verwenden diese Struktur. Zeitstempel sind ISO 8601 in UTC. Die Zähler clicks und uniques umfassen die gesamte Lebensdauer des Links.

Autorisierung

Autorisierte Anfragen tragen das Token im Authorization-Header. Alternativ wird der Header X-API-Key akzeptiert. Tokens werden nie im Query-String übergeben.

Authorization: Bearer YOUR_TOKEN

Ein Kontotoken beginnt mit anon_. Ein Link-Token besteht aus 32 Zeichen. Ein neu erzeugtes Kontotoken macht das vorherige ungültig.

Beispiel:

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

Kontotoken im Konto erzeugen

Endpunkte

Der Request-Body kann als application/json oder als application/x-www-form-urlencoded gesendet werden. Parameternamen und Fehlercodes sind bei allen Endpunkten identisch.

Temporäre E-Mail

Die Kosten sind in Einheiten des Ratenlimits angegeben, siehe Ratenlimits.

Einen Link anlegen

POST /api/v1/links

Die minimale Anfrage enthält nur das Feld url:

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

Mit einem Kontotoken gehört der Link zum Konto und zählt auf dessen Tarif. Ohne Token ist er ein Gastlink auf die IP-Quote:

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

Eine erfolgreiche Anfrage liefert Status 201 mit dem Link, seinem Token und der Anzahl der im aktuellen Quotenzeitraum verbleibenden Links.

Felder der Antwort:

Link mit eigenem Namen

Die Kurzadresse erhält den Namen my-article, wenn er frei ist und den Regeln unten entspricht.

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

Namensregeln:

• Lateinische Buchstaben, Ziffern, Bindestrich und Unterstrich. Ab 5 Zeichen im Free-Tarif und ab 3 in bezahlten Tarifen, höchstens 32. Groß- und Kleinschreibung spielt keine Rolle: Promo und promo sind derselbe Link.
• Seitennamen, Sprachcodes und Dienstwörter sind reserviert.
• Markennamen und anstößige Wörter werden abgelehnt. Namen durchlaufen eine Wortliste und eine automatische Prüfung. Die Zahl eigener Namen pro Stunde ist je Tarif begrenzt.
• Ein vergebener Name liefert Status 409 mit freien Alternativen in suggest.
• Ein Subdomain-Name (sub: true, Tarif Max) ist ein DNS-Label: Buchstaben, Ziffern und Bindestriche, kein Bindestrich am Rand, kein Unterstrich. Namen wie www, mail oder ns1 sind reserviert.

Ein Name lässt sich vor dem Anlegen prüfen:

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

Felder der Prüfantwort:

Mehrere Links auf einmal

Das Feld urls nimmt bis zu 50 Adressen an, als JSON-Array oder als Text mit einer Adresse pro Zeile. Jede Adresse wird ein eigener Link mit eigenem Token, die übrigen Felder gelten für alle. Ein eigener Name ist im Stapel nicht verfügbar.

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

Die Antwort enthält batch: true und ein Array results mit einem Eintrag pro Adresse in der gesendeten Reihenfolge. Eine fehlerhafte Adresse ergibt einen Eintrag mit ok: false und dem Fehlercode, ohne die übrigen zu stoppen.

Weitere Einstellungen

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

Als kostenpflichtig markierte Optionen werden für Gäste und im Free-Tarif ignoriert. Die Antwort gibt die Einstellungen wieder, die der Link tatsächlich erhalten hat.

Links auflisten

GET /api/v1/links

Erfordert ein Kontotoken. Links werden neueste zuerst zurückgegeben.

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

Suche und Tag-Filter lassen sich kombinieren:

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

Felder der Antwort:

Einen Link über die Kurzadresse finden

Ein Link wird über seine numerische ID angesprochen (Feld id, zum Beispiel 4821), nicht über den Namen in der Kurzadresse. Ist nur die Kurzadresse bekannt, lässt sich die ID mit jedem Token ermitteln, das diesen Link verwaltet:

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

Linkdetails und Statistik

GET /api/v1/links/{id}

Liefert die Einstellungen des Links, seinen Status, die Zahl der Besuche und der eindeutigen Besucher über seine gesamte Lebensdauer:

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

Mit einem Kontotoken fügt der Parameter stats einen Besuchsbericht hinzu:

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

Felder der Antwort: stats

Einen Link ändern

PATCH /api/v1/links/{id}

Nur die gesendeten Felder ändern sich:

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

Einen Wert löschen

• password, note und tags: ein leerer String entfernt den Wert.
• expires_days und max_hits: null, ein leerer String oder 0 hebt das Limit auf. self_destruct erlischt, wenn weder Limit noch Lebensdauer bleibt.
• delay: null oder ein leerer String stellt den Tarifstandard wieder her. 0 bedeutet sofortige Weiterleitung.
• url kann nicht geleert werden, und ein reiner Notizlink braucht weiterhin eine Notiz.

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

Einen Link löschen

DELETE /api/v1/links/{id}

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

Nach dem Löschen ist der eigene Name wieder frei. Die Statistik wird mit dem Link gelöscht.

Felder der Antwort:

QR-Code

Für ein HTML-img-Tag fordern Sie den Code über die Kurzadresse an. Dieser Endpunkt braucht kein Token: Die Kurzadresse selbst ist der Schlüssel, und jeder, der sie kennt, kann denselben Code erzeugen.

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

Serverseitiger Code kann das Bild auch per ID mit Token anfordern oder es base64-codiert in JSON erhalten, indem qr=true an den Aufruf zum Anlegen oder zu den Details angehängt wird:

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

Parameter beider Bild-Endpunkte:

Das Feld qr in JSON-Antworten:

Kontodetails

GET /api/v1/me

Erfordert ein Kontotoken. Liefert den Tarif, seine Limits und die verbleibende Quote:

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

API für temporäre E-Mail

Legen Sie eine Adresse auf einer Domain des Tarifs an, fragen Sie sie auf neue Mails ab, lesen Sie Nachrichten samt Authentifizierungsergebnis, antworten Sie auf eingehende Mails und löschen Sie die Adresse, wenn sie nicht mehr gebraucht wird. Nötig ist ein Konto-Token ab Pro. Es gelten die Grenzen des Tarifs.

Eine Adresse lebt so lange, wie der Tarif erlaubt. Die Zahlen stehen in der Tabelle unten. Der Aufruf extend setzt die Uhr zurück. Antworten und freie Sendungen werden pro Adresse und UTC-Tag gezählt.

Die Post einer Adresse wird verschlüsselt gespeichert. Der Schlüssel kommt ein einziges Mal, im Feld key der Antwort auf das Anlegen der Adresse. Der Server bewahrt ihn nicht auf, speichern Sie ihn also selbst. Senden Sie ihn im Header X-Mail-Key, wenn Sie die Liste abrufen, eine Nachricht lesen, einen Anhang laden, Gesendetes abrufen oder antworten. Der Server öffnet die Post nur im Speicher und nur für diese eine Antwort. Ohne den Header kommen die Zeilen mit encrypted = true und ohne Inhalt zurück.

Adresse anlegen

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

Felder der Antwort: address

Die Domains, auf denen Ihr Tarif Adressen anlegen kann:

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

Wie viele Adressen der Tarif gleichzeitig und pro Stunde erlaubt und was davon übrig ist:

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

Felder der Antwort: limits

Schlüssel verloren? Der Aufruf unten stellt einen neuen aus. Post unter dem alten Schlüssel bleibt verschlossen.

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

Posteingang abfragen

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

Felder der Antwort: messages[]

Nachricht lesen

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

Die vollständige Nachricht ergänzt die Listenfelder um:

Eine Nachricht als gelesen oder ungelesen markieren:

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

Antworten

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

Die Antwort geht an die From-Adresse der Nachricht, im selben Thread (In-Reply-To und References), und zählt zu den Antworten des Tarifs pro Tag.

Nachricht senden

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

Gesendet

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

Temporäre E-Mail nach Tarif

Fehler

Fehler werden in einem einheitlichen JSON-Format zurückgegeben:

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

field enthält den Namen des fehlerhaften Parameters oder null, wenn der Fehler kein bestimmtes Feld betrifft. Ein vergebener Name ergänzt suggest, eine kostenpflichtige Option upgrade, Quoten und Ratenlimits den Header Retry-After.

Ratenlimits

Jeder Aufruf kostet Einheiten, und jeder Tarif hat ein Budget an Einheiten pro Minute (siehe Tarife und Limits). Ein Lesezugriff kostet 1 Einheit, eine Listenseite 2, ein QR-Code 3, eine Änderung 3, ein Löschen 2, ein Anlegen 5 plus 1 pro Adresse. Jede Antwort trägt diese Header:

Tarife und Limits

Die genauen Limits jedes Tarifs. Links zählen im Free-Tarif pro Tag und IP-Adresse, in bezahlten Tarifen pro Monat und Konto. Die letzte Spalte nennt die Einstellungen, die ein Tarif nutzen kann.

OpenAPI-Spezifikation

Die vollständige technische Beschreibung als OpenAPI-3.1-Dokument: https://anonym.es/api/v1/openapi.json

Es enthält Schemata und Beispiele aller Anfragen und Antworten, die Tariflimits, die Namensregeln und die Fehlercodes. Es eignet sich für Swagger UI, Postman, Insomnia und Client-Generatoren.