Envoyer un e-mail

Un envoi minimal

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); // "em_…", "accepted"

msg = 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(msg.id, msg.status)

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.Send(context.Background(), 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 {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$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();

bird email send \
  --from hello@yourdomain.com \
  --html '<p>It works.</p>' \
  --subject 'Hello from Bird' \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Hello from Bird",
    "html": "<p>It works.</p>"
  }'

Envoyer avant d'avoir vérifié un domaine

Construire le payload

Destinataires

Contenu

Reply-to et en-têtes personnalisés

• En-têtes d'adressage et de plateforme. Définissez l'adressage du message via les champs dédiés (from, to, cc, bcc, reply_to, subject). Ces noms, ainsi que les en-têtes que nous générons pour vous (Content-Type, Content-Transfer-Encoding, DKIM-Signature, Received, Return-Path), ne peuvent pas être définis ici.
• List-Unsubscribe et List-Unsubscribe-Post sur un envoi marketing. Nous définissons nous-mêmes un en-tête de désinscription en un clic conforme sur ces envois. Sur un envoi transactional, nous laissons les vôtres tels que vous les avez définis.
• Toute valeur contenant un retour chariot ou un saut de ligne.

Suivi

Catégorie et pool d'IP

Référence des champs

Envoyer avec un template

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  category: "transactional",
  template: {
    slug: "welcome-email",
    parameters: { first_name: "Jane" },
  },
});
console.log(msg.id, msg.status);

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["delivered@messagebird.dev"],
    category="transactional",
    template="welcome-email",
    parameters={"first_name": "Jane"},
)
print(msg.id, msg.status)

msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:       "onboarding@messagebird.dev",
	To:         []string{"delivered@messagebird.dev"},
	Category:   "transactional",
	Template:   "welcome-email",
	Parameters: map[string]any{"first_name": "Jane"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    category: 'transactional',
    template: (new EmailMessageSendRequestTemplate())
        ->setSlug('welcome-email')
        ->setParameters(['first_name' => 'Jane']),
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --category transactional \
  --from hello@yourdomain.com \
  --parameters '{"first_name":"Jane"}' \
  --template welcome-email \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "category": "transactional",
    "template": {
      "slug": "welcome-email",
      "parameters": { "first_name": "Jane" }
    }
  }'

• Inline ou par template, jamais les deux. Envoyer template en même temps que subject, html ou text est rejeté avec une 422. Le API rejette aussi les valeurs de variables dans le champ de premier niveau parameters ; pour un envoi par template, elles vont dans template.parameters.
• bird est le seul nom réservé. Un chemin de placeholder commençant par bird. désigne nos propres données, comme le lien de désinscription ou la fiche contact du destinataire, donc une clé template.parameters ne peut pas s'appeler bird. Toute autre clé est libre, et chacune est un mot simple : {"order_number": "A-1043"} remplit {{ order_number }}.
• Un template peut être envoyé maintenant ou plus tard. Ajoutez scheduled_at pour planifier l'envoi. Nous figeons la version publiée, la langue sélectionnée et les valeurs des paramètres à l'acceptation. Si vous supprimez le template avant l'heure d'envoi, le message est rejeté avec generation_failure.
• Un envoi utilise la version publiée du template. Les brouillons ne sont jamais envoyés. Un template inconnu est rejeté avec une 404, et un template sans version publiée avec une 422.
• language sélectionne l'une des langues du template. Omettez-le pour envoyer la langue par défaut du template. Demandez une langue que le template n'a pas, et son propre paramètre on_missing_language décide si la correspondance la plus proche est envoyée à la place ou si l'envoi est rejeté. Un template qui définit language_source_required rejette un envoi qui ne nomme aucune langue.
• La catégorie du template est une valeur par défaut, et la vôtre la remplace. Omettez category et l'envoi hérite de celle du template, de sorte qu'un template transactionnel n'a pas besoin qu'elle soit répétée à chaque appel.

Tags vs métadonnées

• Les tags sont des paires {name, value} structurées : jusqu'à 20 par envoi, nom jusqu'à 32 caractères, valeur jusqu'à 64, lettres ASCII, chiffres, underscore et tiret uniquement, et noms uniques au sein de l'envoi. Les tags sont des dimensions de filtrage : vous pouvez filtrer la liste de messages par tag et découper les analyses et les agrégations du tableau de bord par tag. Utilisez-les pour des libellés à faible cardinalité comme campaign, experiment_variant ou source.
• metadata est un objet JSON arbitraire, jusqu'à 2 Ko sérialisés. Nous le stockons, le renvoyons sur les lectures API et le reproduisons sur chaque événement webhook, ce qui convient au contexte que vous voulez récupérer : identifiants internes, clés étrangères, payloads structurés.

{
  "tags": [{ "name": "campaign", "value": "onboarding" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" }
}

Pièces jointes

Ce que signifie un 202

{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "hello@yourdomain.com" },
  "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"
}

• Les lectures renvoient l'état sans le corps du message. GET /v1/email/messages/{message_id} renvoie l'état du message et des destinataires, jamais le corps html ou text. Lorsque le stockage du contenu est activé pour l'espace de travail, les corps stockés restent disponibles pendant 30 jours maximum depuis GET /v1/email/messages/{message_id}/content.
• Une lecture peut brièvement être en retard sur l'envoi. Un 404 sur les endpoints de lecture juste après un 202 signifie que le message n'est pas encore visible : réessayez après un court instant.

Réessayer en toute sécurité

Envoi par lot

Facturation

Étapes suivantes

• Modèles d'e-mail : créer et publier les modèles que vous envoyez ici
• Catégories : comment marketing et transactional modifient le comportement de suppression
• Suppressions : à qui nous ne distribuons pas, et pourquoi
• Envoi planifié : distribuer à une date future avec scheduled_at
• Bac à sable de test : destinataires sandbox et envoi avant vérification
• Référence API : les schémas complets de requête et de réponse