Sign inGet Started

Invia la tua prima email

Crea una chiave API, invia attraverso il dominio di onboarding condiviso di Bird e verifica il risultato. Per questa guida non è necessario verificare un dominio di invio né pubblicare record DNS. Verifica il tuo dominio prima di inviare ai clienti.

1. Crea una chiave API

Nella dashboard, vai su Developers > Chiavi API e crea una chiave. Le chiavi sono associate a una regione e si presentano come 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 pagina Chiavi API nella dashboard di Bird, con l'elenco delle chiavi e il relativo prefisso mascherato, ambiti e ultimo utilizzo
La chiave completa viene mostrata una sola volta, al momento della creazione. Copiala in un posto sicuro, poi esportala in modo che gli snippet del passaggio 2 possano leggerla:
Esempio di codice
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 consegna sempre, così il risultato è deterministico senza una casella di posta reale.
La chiamata cURL indica l'host US. Se la tua chiave inizia con bk_eu1_, chiama https://eu1.platform.bird.com invece. SDK legge la regione dalla tua 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);
Per i passaggi completi di installazione ed esecuzione in ogni linguaggio o framework, usa i quickstart per SDK.

3. Visualizza il risultato

API risponde con 202: Bird ha accettato l'invio per l'elaborazione asincrona. Controlla lo stato di consegna separatamente. I campi *_count tracciano i destinatari attraverso gli stati di consegna. Nella risposta iniziale, un destinatario è accettato e nessuno è consegnato.
Esempio di codice
{
  "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 attraverso processed fino a delivered. Esegui il polling finché il messaggio sandbox raggiunge delivered:
const msg = await bird.email.get("em_abc123");
msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
msg.delivered_count;
msg.bounced_count;
Nella scheda cURL, sostituisci {region} e {message_id}, e usa $BIRD_API_KEY al posto di $TOKEN.
La lettura ora mostra status: "delivered", delivered_count: 1 e un timestamp delivered_at. Consulta la guida agli eventi per sapere cosa stabilisce delivered per un destinatario reale.
Poiché hai inviato a delivered@messagebird.dev, il risultato è garantito: il messaggio passa attraverso la pipeline di consegna reale di Bird, inclusi gli eventi di produzione e i formati webhook, ma non raggiunge mai una casella di posta reale. Per testare un bounce, invia a bounce@messagebird.dev. La guida al sandbox di test elenca tutti gli indirizzi sandbox e il relativo esito simulato.

Informazioni sul dominio di onboarding

Il mittente condiviso onboarding@messagebird.dev è disponibile per l'onboarding e ha questi limiti:
  • A parte gli indirizzi sandbox @messagebird.dev, consegna solo ai membri verificati del tuo spazio di lavoro; qualsiasi altro destinatario viene rifiutato con un 422.
  • Gli invii sono limitati a 50 destinatari per organizzazione per giorno UTC, contando ogni indirizzo to, cc e bcc, destinatari sandbox inclusi. Oltre il limite, API restituisce un 429.
Quando sei pronto a inviare email a clienti reali, verifica il tuo dominio di invio e inserisci il tuo indirizzo in from; tutto il resto nella richiesta rimane invariato.

Passaggi successivi