Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

E-mails

Envoyez un e-mail ou un lot, programmez-le et suivez-le de l'acceptation à la livraison.

Un e-mail correspond à une requête POST /emails, ou à un message passant par le relais SMTP. BillionSend le vérifie, le stocke et renvoie aussitôt un id. L’envoi se fait en arrière-plan : un 200 signifie que l’e-mail est accepté, pas qu’il est remis.

Envoyer un e-mail

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.emails.send({
  from: "Acme <hello@mail.example.com>",
  to: ["success@simulator.amazonses.com"],
  subject: "Welcome",
  html: "<p>Thanks for signing up.</p>",
});

Le même appel avec curl :

curl -X POST https://api.billionsend.com/emails \
  -H "Authorization: Bearer $BILLIONSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.example.com>",
    "to": ["success@simulator.amazonses.com"],
    "subject": "Welcome",
    "html": "<p>Thanks for signing up.</p>"
  }'
  • from : doit appartenir à un domaine vérifié de votre équipe.
  • to, cc, bcc, reply_to : une adresse ou une liste. to, cc et bcc réunis contiennent au plus 50 destinataires.
  • html et text : au moins l’un des deux est obligatoire. L’envoi avec un identifiant de template n’est pas pris en charge. Un template est un contenu que vous copiez dans une campagne.
  • tags, headers, attachments : consultez les bases de l’API pour les règles, les limites des pièces jointes et l’idempotence.
  • topic_id : les destinataires qui se sont retirés de cette thématique sont ignorés.

L’adresse success@simulator.amazonses.com de ces exemples est celle du simulateur : elle n’écrit à personne, utilisez-la donc pour tester.

Envoyer un lot

POST /emails/batch accepte un tableau d’au plus 100 e-mails. Par défaut, un seul e-mail invalide fait échouer tout le lot. Ajoutez l’en-tête x-batch-validation: permissive pour accepter les e-mails valides : data liste leurs identifiants, et errors liste les autres par position.

Programmer, modifier, annuler

Ajoutez scheduled_at pour envoyer plus tard, jusqu’à 30 jours à l’avance. Il accepte une heure ISO 8601 avec décalage, ou une heure relative comme in 2 hours. Tant qu’un e-mail est programmé, PATCH /emails/{id} modifie son heure et POST /emails/{id}/cancel l’annule.

Suivre un e-mail

GET /emails/{id} renvoie l’e-mail avec last_event, son résultat le plus récent, et un score issu des Insights de délivrabilité. Dans le tableau de bord, E-mails liste tous les e-mails et affiche leurs événements dans l’ordre. Les corps et l’historique sont conservés 30 jours.

Événement Signification
email.scheduled Accepté, en attente de son heure.
email.sent Remis pour livraison.
email.delivered Le serveur du destinataire l’a accepté.
email.delivery_delayed La livraison est retardée et sera retentée.
email.bounced Le serveur du destinataire l’a refusé.
email.complained Le destinataire l’a signalé comme spam.
email.failed Il n’a pas pu être envoyé. L’événement en indique la raison.
email.suppressed Il n’a pas été envoyé parce que tous les destinataires sont supprimés ou désinscrits.
email.opened, email.clicked Le destinataire l’a ouvert ou a cliqué sur un lien, si le suivi est activé.

Chaque événement peut aussi vous être envoyé sous forme de webhook.

Ce qui bloque ou retient un envoi

Un envoi est refusé avec une erreur 4xx qui en donne la raison quand :

  • le domaine de l’expéditeur n’est pas vérifié (422) ;
  • tous les destinataires sont supprimés (422 all_recipients_suppressed) ;
  • vous avez dépassé le volume de votre forfait (429) ;
  • votre taux de rebonds ou de plaintes a suspendu l’envoi (403 sending_paused).

Certains e-mails sont acceptés mais retenus, et partent plus tard : un nouveau domaine au-delà de son plafond quotidien, ou des e-mails qui attendent la réinitialisation d’une limite. Voir Limites d’envoi. L’API et le relais SMTP appliquent les mêmes règles.

Cette page vous a-t-elle été utile ?