Invia la tua prima email
Crea una chiave API, invia tramite il dominio di onboarding condiviso di Bird e controlla il risultato. Per questa guida non devi verificare un dominio di invio né pubblicare record DNS. Verifica il tuo dominio prima di inviare email ai clienti.
1. Crea una chiave API
Nella dashboard, vai a Platform tools > API keys e crea una chiave. Le chiavi sono associate a una regione e hanno la forma bk_us1_... o bk_eu1_...; la regione nel prefisso indica quale host API chiamare: https://us1.platform.bird.com o https://eu1.platform.bird.com.

La chiave completa viene mostrata una sola volta, al momento della creazione. Copiala in un luogo sicuro, poi esportala in modo che gli snippet del passaggio 2 possano leggerla:
export BIRD_API_KEY="bk_us1_..."2. Invia un'email
Invia da onboarding@messagebird.dev, il dominio di onboarding condiviso di Bird, disponibile nel tuo spazio di lavoro senza alcuna configurazione. Indirizza l'email a delivered@messagebird.dev, un destinatario sandbox che riceve sempre il messaggio, così il risultato è deterministico anche senza una casella di posta reale.
La chiamata cURL usa l'host US. Se la tua chiave inizia con bk_eu1_, chiama invece https://eu1.platform.bird.com. SDK legge la regione dalla chiave e seleziona l'host. La scheda TypeScript richiede 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>"
}'Per i passaggi completi di installazione ed esecuzione in ogni linguaggio o framework, consulta i quickstart SDK.
3. Controlla il risultato
L'API risponde con 202: Bird ha accettato l'invio per l'elaborazione asincrona. Controlla lo stato di consegna separatamente. I campi *_count seguono i destinatari attraverso gli stati di consegna. Nella risposta iniziale, un destinatario risulta accettato e nessuno consegnato.
{
"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"
}Recupera il messaggio tramite il suo ID em_ per vederne lo stato attuale. Un messaggio passa da accepted a processed e poi a delivered. Interroga l'API finché il messaggio sandbox non raggiunge 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"Nella scheda cURL, sostituisci {region} e {message_id} e usa $BIRD_API_KEY al posto di $TOKEN.
Ora la lettura mostra status: "delivered", delivered_count: 1 e un timestamp delivered_at. Consulta la guida agli eventi per sapere cosa attesta delivered per un destinatario reale.
Poiché hai inviato a delivered@messagebird.dev, l'esito è garantito: il messaggio attraversa la pipeline di consegna reale di Bird, con eventi e webhook nella stessa forma della produzione, ma non raggiunge mai una casella di posta reale. Per testare un bounce, invia a bounce@messagebird.dev. La guida alla sandbox di test elenca tutti gli indirizzi sandbox e il relativo esito simulato.
Il dominio di onboarding
Il mittente condiviso onboarding@messagebird.dev è disponibile per l'onboarding e ha questi limiti:
- Oltre agli indirizzi sandbox
@messagebird.dev, consegna solo ai membri verificati del tuo spazio di lavoro; qualsiasi altro destinatario viene rifiutato con un422. - Gli invii sono limitati a 50 destinatari per organizzazione per giorno UTC, contando ogni indirizzo
to,ccebcc, compresi i destinatari sandbox. Oltre il limite, l'API restituisce un429.
Quando vuoi inviare email a clienti reali, verifica il tuo dominio di invio e inserisci il tuo indirizzo in from; il resto della richiesta non cambia.
Passaggi successivi
- Quickstart per SDK: lo stesso flusso nel tuo linguaggio e nel tuo framework.
- Domini di invio: verifica il tuo dominio per gli invii in produzione.
- Sandbox di test: tutti gli indirizzi sandbox e gli eventi che ciascuno genera.
- Riferimento API per le email: lo schema completo di richiesta e risposta.
- Iniziare con le email: un video sull'onboarding nella dashboard, che va oltre questa pagina e aggiunge un dominio di invio con i relativi record DNS
Risorse correlate
Continua con la documentazione, le guide e gli esempi per questo argomento.