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 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 :
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);from bird import APIError, Bird
with Bird() as client:
try:
message = client.email.send(
from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
to=["delivered@messagebird.dev"],
subject="Hello from Bird",
html="<p>My first Bird email.</p>",
)
print(message.id, message.status)
except APIError as err:
print("send failed:", err)package main
import (
"encoding/json"
"errors"
"log"
"net/http"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
http.HandleFunc("POST /send", func(w http.ResponseWriter, r *http.Request) {
msg, err := client.Email.Send(r.Context(), bird.EmailSendParams{
From: "onboarding@messagebird.dev",
To: []string{"delivered@messagebird.dev"},
Subject: "Hello from Bird",
HTML: "<p>My first Bird email.</p>",
})
if err != nil {
var apiErr *bird.APIError
if errors.As(err, &apiErr) {
http.Error(w, apiErr.Error(), apiErr.StatusCode)
return
}
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusAccepted)
_ = json.NewEncoder(w).Encode(msg)
})
log.Fatal(http.ListenAndServe(":3000", nil))
}<?php
// Send your first email. Set BIRD_API_KEY in your environment, then run:
// php examples/quickstart-email.php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use MessageBird\Bird;
$bird = new Bird(getenv('BIRD_API_KEY') ?: '');
$message = $bird->email->send(
from: 'Bird <onboarding@messagebird.dev>',
to: ['delivered@messagebird.dev'],
subject: 'Hello from Bird',
html: '<p>My first Bird email.</p>',
);
echo $message->getId(), ' ', $message->getStatus(), "\n";bird email send \
--from 'Bird <onboarding@messagebird.dev>' \
--html '<p>My first Bird email.</p>' \
--subject 'Hello from Bird' \
--to delivered@messagebird.devcurl -X POST "https://us1.platform.bird.com/v1/email/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "onboarding@messagebird.dev", "name": "Bird" },
"to": ["delivered@messagebird.dev"],
"subject": "Hello from Bird",
"html": "<p>My first Bird email.</p>"
}'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é.
{
"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);message = client.email.get("em_abc123")
print(message.id, message.status, message.delivered_count)
print(message.subject, message.subject_recipient_id)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Email.Get(context.Background(), "em_abc123")
if err != nil {
log.Fatal(err)
}
fmt.Println(*msg.Status, *msg.DeliveredCount)
fmt.Println(msg.Subject)
if msg.SubjectRecipientId != nil {
fmt.Println(*msg.SubjectRecipientId)
}
}$message = $bird->email->get('em_01krdgeqcxet5s7t44vh8rt9mg');
echo $message->getStatus();
echo $message->getSubject(), ' ', $message->getSubjectRecipientId();bird email get <message-id>curl -X GET "https://{region}.platform.bird.com/v1/email/messages/{message_id}" \
-H "Authorization: Bearer $TOKEN"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 erreur422. - Les envois sont plafonnés à 50 destinataires par organisation et par jour UTC, en comptant chaque adresse
to,ccetbcc, destinataires de test compris. Au-delà de ce plafond, l’API renvoie une erreur429.
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
- Guides de démarrage rapide par SDK : le même parcours dans votre langage et votre framework.
- Domaines d'envoi : vérifiez votre propre domaine pour les envois en production.
- Sandbox de test : chaque adresse sandbox et les événements qu'elle déclenche.
- Référence de l'API e-mail : le schéma complet des requêtes et des réponses.
- Premiers pas avec l'email : une vidéo de la prise en main dans le tableau de bord, qui va plus loin que cette page et ajoute un domaine d'envoi avec ses enregistrements DNS
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.