Invio di email

Un invio minimale

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>"
  }'

Invio prima della verifica di un dominio

Costruzione del payload

Destinatari

Contenuto

Reply-to e header personalizzati

• Header di indirizzamento e di piattaforma. Imposta l'indirizzamento del messaggio tramite i campi dedicati (from, to, cc, bcc, reply_to, subject). Quei nomi, e gli header che generiamo per te (Content-Type, Content-Transfer-Encoding, DKIM-Signature, Received, Return-Path), non possono essere impostati qui.
• List-Unsubscribe e List-Unsubscribe-Post su un invio marketing. Impostiamo noi un header di disiscrizione con un clic conforme. Su un invio transactional lasciamo i tuoi esattamente come li imposti.
• Qualsiasi valore con un ritorno a capo o un avanzamento riga.

Tracciamento

Categoria e pool di IP

Riferimento dei campi

Invio con 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 o con template, mai entrambi. Inviare template insieme a subject, html o text viene rifiutato con un 422. L'API rifiuta anche i valori delle variabili nel campo di primo livello parameters; in un invio con template vanno in template.parameters.
• bird è l'unico nome riservato. Un percorso placeholder che inizia con bird. identifica dati nostri, come il link di disiscrizione o il record del contatto del destinatario, quindi una chiave template.parameters non può chiamarsi bird. Tutte le altre chiavi sono definibili da te, e ognuna è una singola parola: {"order_number": "A-1043"} riempie {{ order_number }}.
• Un template può essere inviato subito o in un secondo momento. Aggiungi scheduled_at per programmare l'invio. Al momento dell'accettazione fissiamo la versione pubblicata, la lingua selezionata e i valori dei parametri. Se elimini il template prima dell'orario di invio, il messaggio viene rifiutato con generation_failure.
• Un invio usa la versione pubblicata del template. Le bozze non vengono mai inviate. Un template sconosciuto viene rifiutato con un 404, e un template senza versione pubblicata con un 422.
• language seleziona una delle lingue del template. Omettilo per inviare la lingua predefinita del template. Chiedi una lingua che il template non ha, e la sua impostazione on_missing_language decide se viene inviata la corrispondenza più vicina o se l'invio viene rifiutato. Un template che imposta language_source_required rifiuta un invio che non specifica alcuna lingua.
• La categoria del template è un valore predefinito, e la tua lo sovrascrive. Ometti category e l'invio eredita quella del template, quindi un template transazionale non ha bisogno di ripeterla a ogni chiamata.

Tag e metadati a confronto

• I tags sono coppie {name, value} strutturate: fino a 20 per invio, nome fino a 32 caratteri, valore fino a 64, solo lettere ASCII, cifre, underscore e trattino, e nomi univoci all'interno dell'invio. I tag sono dimensioni di filtro, quindi puoi filtrare l'elenco messaggi per tag e segmentare analytics e aggregazioni dashboard per tag. Usali per etichette a bassa cardinalità come campaign, experiment_variant o source.
• I metadata sono un oggetto JSON arbitrario, fino a 2 KB serializzati. Li conserviamo, li restituiamo nelle letture API e li includiamo in ogni evento webhook, quindi sono adatti a contesti che vuoi ricevere indietro: ID interni, chiavi esterne, payload strutturati.

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

Allegati

Cosa significa 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"
}

• Le letture restituiscono lo stato senza il corpo. GET /v1/email/messages/{message_id} restituisce lo stato del messaggio e dei destinatari, mai il corpo html o text. Quando l'archiviazione dei contenuti è abilitata per lo spazio di lavoro, i corpi archiviati restano disponibili fino a 30 giorni da GET /v1/email/messages/{message_id}/content.
• Una lettura può seguire brevemente l'invio. Un 404 sugli endpoint di lettura subito dopo un 202 significa che il messaggio non è ancora visibile: riprova dopo un momento.

Riprovare in sicurezza

Invio in batch

Fatturazione

Prossimi passi

• Template email: crea e pubblica i template che invii da qui
• Categorie: come marketing e transactional cambiano il comportamento delle soppressioni
• Soppressioni: a chi non consegniamo e perché
• Invio programmato: consegna in un momento futuro con scheduled_at
• Sandbox di test: destinatari sandbox e invio prima della verifica
• Riferimento API: gli schemi completi di richiesta e risposta