---
title: E-mails
description: Envoyez un e-mail ou un lot, programmez-le et suivez-le de l'acceptation à la livraison.
seo:
  title: API email pour envoyer des e-mails
ai:
  exclude: true
---

Un e-mail correspond à une requête `POST /emails`, ou à un message passant par le [relais SMTP](/docs/fr/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

```ts
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` :

```bash
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é](/docs/fr/concepts/domains) 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](/docs/fr/concepts/templates) est un contenu que vous copiez dans une campagne.
- `tags`, `headers`, `attachments` : consultez les [bases de l'API](/docs/fr/api-reference/basics) 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](/docs/fr/concepts/topics) 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é](/docs/fr/concepts/deliverability-insights). 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](/docs/fr/concepts/tracking) est activé. |

Chaque événement peut aussi vous être envoyé sous forme de [webhook](/docs/fr/concepts/webhooks).

## 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](/docs/fr/concepts/suppressions) (`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](/docs/fr/concepts/sending-limits). L'API et le relais SMTP appliquent les mêmes règles.
