Connexion Tester gratuitement

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

Créez un test via REST, envoyez votre e-mail à chaque boîte renvoyée avec l’id du test à l’intérieur et récupérez en JSON le dossier et l’onglet où il arrive dans chacune.

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

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

# choisissez les id voulus, puis passez-les à la requête suivante
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] }'

# renvoie l’id du test et les boîtes témoins à qui envoyer
{
  "id": "7Hq2xLpV0aKd",
  "mailboxes": [
    { "id": 3, "name": "Gmail", "address": "..." },
    { "id": 7, "name": "Outlook", "address": "..." }
  ]
}

# envoyez à chaque adresse avec l’id du test dans l’objet ou le corps, puis lisez le résultat
curl https://api.unspam.email/ext/v2/inbox-placement/7Hq2xLpV0aKd \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# réponse (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
19
Résultats
Par boîte
Authentification
Token bearer
Limite de requêtes
100 par minute

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, onglet ou spam, boîte par boîte.

Le tableau results[] contient une entrée par boîte avec le status de livraison, le tab où l’e-mail est arrivé, le sender et la sender_ip vus par le destinataire, et le nombre de listes noires publiques dans blacklists.

Planifiez, interrogez, alertez.

Les endpoints /scheduled-tests exécutent des tests de placement selon le calendrier que vous fixez, avec des réglages d’alerte et des résultats par exécution. Reliez le JSON à Datadog, PagerDuty, Slack ou à l’outil qui alerte déjà votre équipe. Voir les tests automatiques.

Suivez l’évolution du placement dans le temps.

GET /inbox-placement?page=N&per_page=15 renvoie les tests que vous avez créés via l’API, avec l’id, le statut, les horodatages et le report_url hébergé. Relisez n’importe lequel par son id pour suivre l’évolution par boîte de semaine en semaine, sans créer votre propre stockage.

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.

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

Chaque results[].tab indique où l’e-mail est arrivé dans cette boîte : Inbox, Spam ou un onglet Gmail comme Promotions, Social, Updates ou Forums. Il reste à null jusqu’à l’arrivée du message. Les scores agrégés cachent l’endroit où la réputation se dégrade vraiment ; ceci répond directement à la question.

Le champ status indique la livraison : success dès que la boîte a reçu le message, pending tant que nous l’attendons et failed s’il n’est jamais arrivé.

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

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.

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

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: 3
  • Outlook id: 7
  • 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. Indiquez l’id du test dans l’objet ou le corps 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 results[] avec, pour chaque boîte, le status, le tab, la sender_ip et le compteur blacklists. Interrogez jusqu’à ce que le status du test lui-même quitte pending : il se termine en success ou failed.

Les endpoints derrière.

19 endpoints, avec le même token que le reste de l’API. Le document OpenAPI détaille chaque paramètre et code de réponse.

Document OpenAPI
Inbox Placement 4 appels
  • GET /inbox-placement
  • POST /inbox-placement
  • GET /inbox-placement/mailboxes
  • GET /inbox-placement/{id}
Automatic Testing: Senders 6 appels
  • 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 9 appels
  • 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
  • GET /scheduled-tests/{id}/runs
  • GET /scheduled-tests/{id}/runs/{runId}

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 inclus dans le plan sur mesure, que vous achetez en ligne : choisissez le volume mensuel de chaque test sur la page des tarifs, à partir d’un minimum de $5, et les tarifs baissent à mesure que vous grandissez. Vous pouvez l’intégrer à votre propre produit et le revendre sous votre propre marque. Pour toute autre question, ouvrez un ticket d’assistance.
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 une limite plus élevée, ouvrez un ticket d’assistance 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, avec l’id du test dans l’objet ou le corps pour que nous puissions le rattacher. Ensuite, GET /ext/v2/inbox-placement/{id} renvoie les verdicts par boîte, et le status du test se termine en success ou failed.
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 ?
Envoyez le POST depuis votre étape de build (curl, Node, Python ou tout 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 success ou failed.
Puis-je l’intégrer à mon propre produit et le revendre ?
Oui, avec le plan sur mesure. Chaque test de placement revient en JSON avec le dossier où chaque boîte a classé votre e-mail : vous pouvez donc l’afficher dans votre propre interface et le revendre à vos clients sous votre propre marque.
Puis-je prévisualiser le même e-mail dans de vrais clients ?
Oui. POST /ext/v2/client-previews avec email_source à inbox-placement et l’id du test en source_id affiche le message envoyé dans de vrais clients et appareils. Le résultat du test porte alors son client_preview_id. Voir l’API d’aperçu d’e-mails.

Intégrez les tests de placement à votre stack.

L’accès à l’API est inclus dans le plan sur mesure, qui s’achète en ligne à partir d’un minimum de $5 par mois. Intégrez-le à votre propre produit et revendez-le sous votre propre marque.

Voir les tarifs Présentation de l’API