Sign inGet Started

Envoyer votre premier e-mail

Créez une clé API, envoyez un message via le domaine d'intégration partagé de Bird, puis vérifiez le résultat. Ce guide ne vous demande ni de vérifier un domaine d'envoi, ni de publier des enregistrements DNS. Vérifiez votre propre domaine avant d'envoyer des e-mails à vos clients.

1. Créer une clé API

Dans le tableau de bord, ouvrez Platform tools > API keys et créez une clé. Chaque clé est liée à une région et ressemble à bk_us1_... ou bk_eu1_.... La région indiquée dans le préfixe détermine l'hôte API à appeler : https://us1.platform.bird.com ou https://eu1.platform.bird.com.

La page des clés API dans le tableau de bord Bird, qui liste les clés avec leur préfixe masqué, leurs portées et leur date de dernière utilisation

La clé complète n'est affichée qu'une seule fois, au moment de sa création. Copiez-la en lieu sûr, puis exportez-la pour que les extraits de code de l'étape 2 puissent la lire :

Exemple de code
export BIRD_API_KEY="bk_us1_..."

2. Envoyer un e-mail

Envoyez depuis onboarding@messagebird.dev, le domaine d'intégration partagé de Bird, disponible dans votre espace de travail sans aucune configuration. Adressez le message à delivered@messagebird.dev, un destinataire de test dont la livraison réussit toujours : le résultat est ainsi prévisible sans boîte de réception réelle.

L'appel cURL utilise l'hôte américain. Si votre clé commence par bk_eu1_, appelez plutôt https://eu1.platform.bird.com. Le SDK lit la région dans votre clé et choisit l'hôte correspondant. L'onglet TypeScript nécessite npm install @messagebird/sdk.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});

console.log(msg.id, msg.status);

Pour les étapes complètes d'installation et d'exécution dans chaque langage ou framework, consultez les guides de démarrage rapide SDK.

3. Consulter le résultat

L’API répond avec 202 : Bird a accepté l’envoi pour un traitement asynchrone. Vérifiez le statut de livraison séparément. Les champs *_count suivent les destinataires à travers les états de livraison. Dans la réponse initiale, un destinataire est accepté et aucun n’est livré.

Exemple de code
{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "onboarding@messagebird.dev" },
  "to": [{ "email": "delivered@messagebird.dev" }],
  "subject": "Hello from Bird",
  "accepted_count": 1,
  "processed_count": 0,
  "delivered_count": 0,
  "deferred_count": 0,
  "bounced_count": 0,
  "complained_count": 0,
  "rejected_count": 0,
  "open_count": 0,
  "click_count": 0,
  "track_opens": true,
  "track_clicks": true,
  "created_at": "2026-07-23T13:58:20.866Z"
}

Récupérez le message à partir de son ID em_ pour connaître son état actuel. Un message passe de accepted à delivered en passant par processed. Interrogez l’API à intervalles réguliers jusqu’à ce que le message de test atteigne l’état delivered :

const msg = await bird.email.get("em_abc123");
msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
msg.delivered_count;
msg.bounced_count;
console.log(msg.subject, msg.subject_recipient_id);

Dans l’onglet cURL, remplacez {region} et {message_id}, et utilisez $BIRD_API_KEY à la place de $TOKEN.

La lecture affiche maintenant status: "delivered", delivered_count: 1 et un horodatage delivered_at. Consultez le guide des événements pour savoir ce que delivered établit pour un destinataire réel.

Comme vous avez envoyé le message à delivered@messagebird.dev, le résultat est garanti : le message passe par le véritable pipeline de livraison de Bird, avec les mêmes formats d’événements et de webhooks qu’en production, mais n’atteint jamais une vraie boîte de réception. Pour tester un rebond, envoyez à bounce@messagebird.dev. Le guide de l’environnement de test répertorie chaque adresse de test et le résultat qu’elle simule.

À propos du domaine d’intégration

L’expéditeur partagé onboarding@messagebird.dev est disponible pour l’intégration et présente les limites suivantes :

  • En dehors des adresses de test @messagebird.dev, il ne livre qu’aux membres vérifiés de votre espace de travail ; tout autre destinataire est refusé avec une erreur 422.
  • Les envois sont plafonnés à 50 destinataires par organisation et par jour UTC, en comptant chaque adresse to, cc et bcc, destinataires de test compris. Au-delà de ce plafond, l’API renvoie une erreur 429.

Lorsque vous êtes prêt à envoyer des e-mails à de vrais clients, vérifiez votre propre domaine d’envoi et indiquez votre propre adresse dans from ; le reste de la requête ne change pas.

Étapes suivantes

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.