Sign inGet Started

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 pagina API Keys nella dashboard di Bird, che elenca le chiavi con il prefisso mascherato, gli ambiti e l'ora dell'ultimo utilizzo

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:

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

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.

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

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 un 422.
  • Gli invii sono limitati a 50 destinatari per organizzazione per giorno UTC, contando ogni indirizzo to, cc e bcc, compresi i destinatari sandbox. Oltre il limite, l'API restituisce un 429.

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