API de placement en boîte de réception.

Listez les boîtes que vous voulez tester, créez un test de placement, envoyez votre e-mail à chaque adresse renvoyée, puis récupérez en JSON le dossier d’arrivée boîte par boîte (boîte de réception / promotions / spam), avec l’analyse de l’expéditeur et l’exposition aux listes noires.

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

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

# pick the IDs you want to test,
# pass them in the next 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] }'

# response (201)
{
  "id": "abc123",
  "mailboxes": [
    { "id": 3, "name": "Gmail", "address": "..." }
  ]
}

# send your email to each address,
# with the test id somewhere in the body.
curl https://api.unspam.email/ext/v2/inbox-placement/abc123 \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# response (200)
{
  "id": "abc123",
  "status": "completed",
  "results": [
    {
      "mailbox": { "name": "Gmail", ... },
      "status":     "delivered",
      "tab":        "inbox",
      "sender_ip":  "192.0.2.1",
      "blacklists": 0
    }
  ],
  "report_url": "https://unspam.email/inbox-test/abc123"
}

Quatre types de requête. Une seule clé d’API.

Une seule clé couvre les quatre endpoints. POST /inbox-placement dépose votre message dans nos boîtes de test et renvoie le dossier d’arrivée boîte par boîte ; la même clé note aussi le contenu, récupère les prévisualisations dans les clients de messagerie et génère des heatmaps.

Tests de spam

POST /spam-checkScore, analyse de l’expéditeur, détail de chaque vérification. Conçu pour les plateformes d’envoi et les équipes CRM.

Inbox Placement

POST /inbox-placementEnvoyez à nos boîtes de test et obtenez le dossier d’arrivée boîte par boîte (boîte de réception / promotions / spam) et l’exposition aux listes noires.

Prévisualisations dans les clients de messagerie

GET /spam-check/{id}/client-previewsVotre e-mail rendu dans plus de 50 clients de messagerie et appareils réels, en mode clair et sombre. Voir l’API de prévisualisation des e-mails.

Heatmaps d’e-mails

GET /spam-check/{id}/heatmapDes heatmaps de focus et d’attention générées par IA sur les trois tailles d’appareil.

Pourquoi les équipes choisissent Unspam pour suivre leur placement.

Testez toutes les boîtes ou seulement une partie.

Passez {"mailboxes": [3, 7, 23]} pour limiter un test à certains fournisseurs. Laissez le corps vide pour couvrir toutes les boîtes activées. Les ID de boîte viennent de GET /inbox-placement/mailboxes.

Boîte de réception / Promotions / Spam par fournisseur.

Le tableau results[] porte une entrée par boîte, avec le status de livraison, l’onglet de destination tab, les champs sender et sender_ip vus par le destinataire, et le nombre d’apparitions sur les listes noires publiques.

Planifiez, interrogez, alertez.

Branchez des tests de placement planifiés sur votre stack de supervision. Reliez la réponse JSON à Datadog, PagerDuty, Slack ou à l’outil qui alerte déjà votre équipe.

Suivez l’évolution du placement dans le temps.

Les tests passés restent conservés. GET /inbox-placement?page=N&per_page=15 renvoie la liste paginée avec id, status, horodatages et le report_url hébergé. Suivez la dérive boîte par boîte d’une semaine à l’autre sans reconstruire de stockage chez vous.

Ce que renvoie chaque test de placement en boîte de réception.

Un verdict de dossier boîte par boîte, l’analyse de l’expéditeur et l’exposition aux listes noires : les données dont votre stack de supervision a besoin pour agir.

01

Un verdict de dossier boîte par boîte, pas un score.

Le champ results[].tab indique où l’e-mail est arrivé chez ce fournisseur précis : "inbox", "promotions", "spam" ou "missing". Les scores agrégés masquent l’endroit où la réputation se dégrade réellement. Ici, la réponse est directe.

Le champ status indique la livraison : "delivered", "pending" ou "missing" si la boîte de test n’a jamais reçu le message.

  • Gmail boîte de réception
  • Outlook promotions
  • Yahoo Mail spam
  • Zoho boîte de réception
  • AOL boîte de réception
02

L’analyse de l’expéditeur et du SMTP dans le même payload.

Chaque entrée de résultat porte sender, sender_ip et blacklists (le nombre de listes noires publiques sur lesquelles le moteur a détecté l’IP d’envoi au moment de la livraison). Vous voyez ce que le destinataire a vu, pas seulement ce que montrent vos propres journaux.

Envoyez-les directement dans votre tableau de bord de réputation ou servez-vous-en pour brider une IP problématique avant qu’elle ne pénalise la campagne suivante.

LIVRÉ
status
delivered
tab
inbox
sender
send@yourdomain.com
sender_ip
192.0.2.1
blacklists
0
03

Filtrez sur les fournisseurs utilisés par vos clients.

GET /ext/v2/inbox-placement/mailboxes renvoie chaque boîte activée avec son id, son name et son address en service. Choisissez les ID qui correspondent à votre audience et passez-les à l’endpoint de création.

Inutile de couvrir tous les fournisseurs pour un SaaS B2B qui envoie surtout vers Outlook en entreprise. Ciblez serré et économisez votre limite.

  • Gmail id: 1
  • Gmail Workspace id: 3
  • Outlook id: 7
  • Yahoo Mail id: 12
  • Zoho id: 18
  • AOL id: 23

Le fonctionnement de l’API en quatre étapes.

Le placement en boîte de réception est asynchrone : listez les boîtes, créez un test, envoyez votre e-mail à chaque adresse renvoyée, puis lisez les verdicts fournisseur par fournisseur.

  1. 01

    Lister les boîtes disponibles

    GET /ext/v2/inbox-placement/mailboxes renvoie l’ensemble des boîtes activées avec des ID stables. Utile une fois à la configuration, puis à intervalles réguliers à mesure que de nouveaux fournisseurs arrivent.

  2. 02

    Créer un test de placement

    POST /ext/v2/inbox-placement avec un filtre mailboxes facultatif. La réponse 201 renvoie l’id du test et la liste des address de boîtes auxquelles vous devez livrer.

  3. 03

    Envoyer votre e-mail à chaque adresse

    Livrez depuis votre plateforme à chaque adresse renvoyée. Placez l’id du test quelque part dans le corps de l’e-mail pour que notre moteur puisse rattacher le message au test.

  4. 04

    Lire les verdicts boîte par boîte

    GET /ext/v2/inbox-placement/{id} renvoie le tableau results[] avec, pour chaque boîte, le tab, le status, la sender_ip et le compteur blacklists, dès que status === "completed".

Questions fréquentes sur l’API.

Fonctionnement des boîtes de test, interrogation, limites de requêtes et signification du verdict de chaque fournisseur.

Comment obtenir l’accès à l’API ?
L’accès à l’API est fourni avec notre plan White Label, entièrement sur mesure : les limites de tests de placement en boîte de réception, de tests de spam, de captures d’écran et de heatmaps sont dimensionnées pour votre compte. Contactez un commercial en indiquant le volume attendu et nous définirons l’offre adaptée.
Quelles sont les limites de requêtes ?
La limite publique est de 100 requêtes par minute par IP ou par compte authentifié. Cela couvre la majeure partie du trafic de production. S’il vous faut davantage de capacité en pointe ou une file dédiée, ouvrez le chat en indiquant le débit attendu.
Comment fonctionne le flux créer puis envoyer ?
Trois appels. POST /ext/v2/inbox-placement renvoie un id de test et une liste d’adresses de boîtes. Votre plateforme livre le véritable e-mail à chacune d’elles, avec l’id du test dans le corps pour que nous puissions le rattacher. Ensuite, GET /ext/v2/inbox-placement/{id} renvoie les verdicts boîte par boîte dès que status === "completed".
Quelles boîtes sont disponibles ?
Nous testons chez les fournisseurs de messagerie personnels et professionnels les plus répandus. Pour la liste toujours à jour, avec les ID que vous pouvez passer pour cibler un test, appelez GET /ext/v2/inbox-placement/mailboxes.
Le placement est-il déterministe ?
Non. Les filtres des fournisseurs fonctionnent par échantillonnage et dépendent de la réputation d’expéditeur, de l’engagement des destinataires et du poids actuel des filtres. Prenez le résultat comme un signal directionnel fort, pas comme la garantie que vos prochains envois arriveront dans le même dossier.
Que m’indique le compteur de listes noires ?
Le champ blacklists de chaque résultat est le nombre de listes noires publiques sur lesquelles notre moteur a détecté l’IP d’envoi au moment de la livraison. Zéro est l’état attendu ; au-delà, c’est un problème de réputation à traiter avec votre expéditeur ou votre ESP.
Puis-je lister les tests passés ?
Oui. GET /ext/v2/inbox-placement?page=1&per_page=15 renvoie une liste paginée des tests créés via l’API, avec id, status, horodatages et le report_url de chacun.
Comment déclencher des tests de placement depuis un pipeline CI ?
Faites un POST depuis votre étape de build (curl, Node, Python ou n’importe quel client HTTP). Lisez la réponse, envoyez votre e-mail, puis interrogez GET /inbox-placement/{id} avec un back-off exponentiel jusqu’à ce que status vaille "completed".

Intégrez les tests de placement à votre stack.

L’accès à l’API est inclus dans le plan White Label. Les tarifs sont sur la page publique, les limites sur mesure se discutent par chat.

Voir les tarifs