Inbox-Placement-API.

Leg per REST einen Test an, schick deine E-Mail mit der Test-ID an jedes zurückgegebene Postfach und lies als JSON aus, in welchem Ordner und Tab sie jeweils gelandet ist.

curl https://api.unspam.email/ext/v2/inbox-placement/mailboxes \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# Antwort (200)
[
  { "id": 3, "name": "Gmail", "address": "..." },
  { "id": 7, "name": "Outlook", "address": "..." },
  ...
]

# wähle die gewünschten IDs und übergib sie im nächsten Request
curl -X POST https://api.unspam.email/ext/v2/inbox-placement \
  -H "Authorization: Bearer $UNSPAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mailboxes": [3, 7] }'

# liefert die Test-ID und die Seed-Postfächer zum Senden
{
  "id": "7Hq2xLpV0aKd",
  "mailboxes": [
    { "id": 3, "name": "Gmail", "address": "..." },
    { "id": 7, "name": "Outlook", "address": "..." }
  ]
}

# sende an jede Adresse mit der Test-ID im Betreff oder Text und lies dann das Ergebnis
curl https://api.unspam.email/ext/v2/inbox-placement/7Hq2xLpV0aKd \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# Antwort (200)
{
  "status": "success",
  "results": [
    {
      "mailbox": { "id": 3, "name": "Gmail", ... },
      "status": "success",
      "tab": "Promotions",
      "sender": "news@yourdomain.com",
      "sender_ip": "192.0.2.1",
      "blacklists": 0
    }
  ],
  "report_url": "https://unspam.email/inbox-test/7Hq2xLpV0aKd"
}
Endpoints
20
Ergebnisse
Pro Postfach
Authentifizierung
Bearer-Token
Rate-Limit
100 pro Minute

Warum Teams für Placement-Monitoring auf Unspam setzen.

Alle Postfächer testen oder eine Teilmenge wählen.

Übergib {"mailboxes": [3, 7, 23]}, um einen Test auf bestimmte Anbieter zu begrenzen. Lass den Body leer, um an jedes aktive Postfach zu senden. Die Postfach-IDs kommen aus GET /inbox-placement/mailboxes.

Posteingang, Tab oder Spam, Postfach für Postfach.

Das Array results[] enthält pro Postfach einen Eintrag mit dem Zustell-status, dem tab, in dem die E-Mail gelandet ist, dem sender und der sender_ip, die der Empfänger gesehen hat, und der Anzahl öffentlicher Blacklists in blacklists.

Planen, abfragen, alarmieren.

Die /scheduled-tests-Endpoints führen Placement-Tests nach deinem Zeitplan aus, mit Alarm-Einstellungen und Ergebnissen pro Lauf. Leite das JSON an Datadog, PagerDuty, Slack oder das Tool weiter, das dein Team ohnehin schon alarmiert. Siehe automatische Tests.

Placement über die Zeit verfolgen.

GET /inbox-placement?page=N&per_page=15 liefert die Tests, die du über die API angelegt hast, mit ID, Status, Zeitstempeln und der gehosteten report_url. Lies jeden davon per ID wieder aus, um Veränderungen pro Postfach von Woche zu Woche zu verfolgen, ohne eigenen Speicher aufzubauen.

Was jeder Inbox-Placement-Test zurückgibt.

Ein Ordner-Ergebnis pro Postfach, Absender-Forensik und Blacklist-Treffer: die Daten, mit denen dein Monitoring-Stack handeln kann.

Ein Ordner-Ergebnis pro Postfach, kein Score.

Jedes results[].tab zeigt, wo die E-Mail in diesem Postfach gelandet ist: Inbox, Spam oder ein Gmail-Tab wie Promotions, Social, Updates oder Forums. Bis die Nachricht ankommt, bleibt es null. Aggregierte Scores verbergen, wo die Reputation wirklich Schaden nimmt; das hier beantwortet die Frage direkt.

Das Feld status zeigt die Zustellung: success, sobald das Postfach die Nachricht hat, pending, solange wir darauf warten, und failed, wenn sie nie angekommen ist.

  • Gmail Promotions
  • Outlook Inbox
  • Yahoo Mail Spam
  • Zoho Inbox
  • AOL null

Absender- und SMTP-Forensik im selben Payload.

Jeder Ergebniseintrag enthält sender, sender_ip und blacklists (die Anzahl der öffentlichen Blacklists, auf denen unsere Engine die sendende IP zum Zustellzeitpunkt gefunden hat). Du siehst, was der Empfänger gesehen hat, nicht nur, was in deinen eigenen Logs steht.

Leite diese Werte direkt in dein Reputations-Dashboard oder drossle damit eine problematische IP, bevor sie die nächste Kampagne trifft.

  • status success
  • tab Inbox
  • sender send@yourdomain.com
  • sender_ip 192.0.2.1
  • blacklists 0

Auf die Anbieter filtern, die deine Kunden nutzen.

GET /ext/v2/inbox-placement/mailboxes gibt jedes aktive Postfach mit id, name und der aktiven address zurück. Wähl die IDs, die zu deiner Zielgruppe passen, und übergib sie an den Endpoint, der den Test anlegt.

Ein B2B-SaaS, das vor allem an Outlook im Unternehmen sendet, muss nicht jeden Anbieter mittesten. Grenz eng ein und spar dir dein Limit.

  • Gmail id: 3
  • Outlook id: 7
  • AOL id: 23

So funktioniert die API in vier Schritten.

Inbox Placement läuft asynchron: Postfächer auflisten, Test anlegen, deine E-Mail an jede zurückgegebene Adresse schicken, dann die Ergebnisse pro Anbieter auslesen.

  1. 01

    Verfügbare Postfächer auflisten

    GET /ext/v2/inbox-placement/mailboxes gibt alle aktiven Postfächer mit stabilen IDs zurück. Einmal beim Setup nützlich, danach turnusmäßig, sobald neue Anbieter dazukommen.

  2. 02

    Placement-Test anlegen

    POST /ext/v2/inbox-placement mit optionalem mailboxes-Filter. Die 201-Response liefert die Test-id und die Liste der Postfächer mit der address, an die du zustellen musst.

  3. 03

    E-Mail an jede Adresse schicken

    Stell die E-Mail von deiner Plattform an jede zurückgegebene Adresse zu. Nimm die Test-id in den Betreff oder Text auf, damit unsere Engine die Nachricht dem Test zuordnen kann.

  4. 04

    Ergebnisse pro Postfach auslesen

    GET /ext/v2/inbox-placement/{id} liefert results[] mit status, tab, sender_ip und der blacklists-Anzahl pro Postfach. Frag ab, bis der status des Tests selbst nicht mehr pending ist: Er endet als success oder failed.

Die Endpoints dahinter.

20 Endpoints, mit demselben Token wie die restliche API. Im OpenAPI-Dokument stehen alle Parameter und Response-Codes.

OpenAPI-Dokument
Inbox Placement 4 Aufrufe
  • GET /inbox-placement
  • POST /inbox-placement
  • GET /inbox-placement/mailboxes
  • GET /inbox-placement/{id}
Automatic Testing: Senders 6 Aufrufe
  • GET /scheduled-test-senders
  • POST /scheduled-test-senders
  • GET /scheduled-test-senders/{id}
  • PUT /scheduled-test-senders/{id}
  • DELETE /scheduled-test-senders/{id}
  • POST /scheduled-test-senders/{id}/test-connection
Automatic Testing: Tests 10 Aufrufe
  • GET /scheduled-tests
  • POST /scheduled-tests
  • GET /scheduled-tests/{id}
  • PUT /scheduled-tests/{id}
  • PATCH /scheduled-tests/{id}
  • DELETE /scheduled-tests/{id}
  • POST /scheduled-tests/{id}/dispatch-now
  • PUT /scheduled-tests/{id}/email
  • GET /scheduled-tests/{id}/runs
  • GET /scheduled-tests/{id}/runs/{runId}

Häufige Fragen zur API.

Wie die Postfächer funktionieren, Polling, Rate Limits und was das Ergebnis pro Anbieter bedeutet.

Wie bekomme ich API-Zugang?
API-Zugang ist im individuellen Plan enthalten, den du online buchst: Wähle auf der Preisseite das monatliche Volumen jedes Tests, ab einem Mindestbetrag von $5, und die Preise sinken, wenn du wächst. Du kannst ihn in dein eigenes Produkt einbauen und unter deiner eigenen Marke weiterverkaufen. Für alles andere eröffne ein Support-Ticket.
Wie sehen die Rate Limits aus?
Das öffentliche Limit liegt bei 100 Requests pro Minute pro IP oder pro authentifiziertem Konto. Das deckt den meisten Produktions-Traffic ab. Wenn du ein höheres Limit brauchst, eröffne ein Support-Ticket und nenne deinen erwarteten Durchsatz.
Wie läuft der Ablauf aus Anlegen und Senden ab?
Drei Aufrufe. POST /ext/v2/inbox-placement gibt eine Test-id und eine Liste von Postfach-Adressen zurück. Deine Plattform stellt die echte E-Mail an jede davon zu, mit der Test-ID im Betreff oder Text, damit wir sie zuordnen können. Dann liefert GET /ext/v2/inbox-placement/{id} die Ergebnisse pro Postfach, und der status des Tests endet als success oder failed.
Welche Postfächer stehen zur Verfügung?
Wir testen gegen die verbreitetsten privaten und geschäftlichen E-Mail-Anbieter. Die immer aktuelle Liste (samt der IDs, mit denen du einen Test eingrenzt) holst du über GET /ext/v2/inbox-placement/mailboxes.
Ist das Placement deterministisch?
Nein. Die Filter der Anbieter arbeiten stichprobenbasiert und hängen von der Absender-Reputation, dem Engagement der Empfänger und den aktuellen Filtergewichten ab. Nimm das Ergebnis als starken Richtungswert, nicht als Garantie, dass künftige Sendungen im selben Ordner landen.
Was sagt mir die Blacklist-Anzahl?
Das Feld blacklists in jedem Ergebnis ist die Anzahl der öffentlichen Blacklists, auf denen unsere Engine die sendende IP zum Zustellzeitpunkt gefunden hat. Null ist der Normalfall; alles darüber ist ein Reputationsproblem, das du über deinen Absender oder ESP klären solltest.
Kann ich frühere Tests auflisten?
Ja. GET /ext/v2/inbox-placement?page=1&per_page=15 gibt eine paginierte Liste der über die API erstellten Tests zurück, mit id, status, Zeitstempeln und der jeweiligen report_url.
Wie stoße ich Placement-Tests aus einer CI-Pipeline an?
Sende den POST aus deinem Build-Schritt (curl, Node, Python oder ein beliebiger HTTP-Client). Lies die Antwort, schick deine E-Mail und frag dann GET /inbox-placement/{id} mit exponentiellem Back-off ab, bis status auf success oder failed steht.
Kann ich das in mein eigenes Produkt einbauen und weiterverkaufen?
Ja, mit dem individuellen Plan. Jeder Inbox-Placement-Test kommt als JSON mit dem Ordner zurück, in dem jedes Postfach deine E-Mail abgelegt hat, sodass du ihn in deiner eigenen Oberfläche zeigen und unter deiner eigenen Marke an deine Kunden weiterverkaufen kannst.
Kann ich dieselbe E-Mail in echten Clients ansehen?
Ja. POST /ext/v2/client-previews mit email_source auf inbox-placement und der Test-ID als source_id rendert die gesendete Nachricht in echten Clients und Geräten. Das Testergebnis trägt dann seine client_preview_id. Siehe die E-Mail-Vorschau-API.

Hol Placement-Tests in deinen Stack.

API-Zugang ist im individuellen Plan enthalten, den du online ab einem Mindestbetrag von $5 im Monat buchst. Bau ihn in dein eigenes Produkt ein und verkauf ihn unter deiner eigenen Marke weiter.