Envía tu primer correo electrónico
Crea una clave API, envía a través del dominio compartido de onboarding de Bird y consulta el resultado. No necesitas verificar un dominio de envío ni publicar registros DNS para esta guía. Verifica tu propio dominio antes de enviar a clientes.
1. Crea una clave API
En el dashboard, ve a Developers > Claves API y crea una clave. Las claves están asociadas a una región y tienen el formato bk_us1_... o bk_eu1_...; la región en el prefijo te indica qué host API llamar: https://us1.platform.bird.com o https://eu1.platform.bird.com.

La clave completa se muestra una sola vez, en el momento de crearla. Cópiala en un lugar seguro y luego expórtala para que los fragmentos de código del paso 2 puedan leerla:
Ejemplo de código
export BIRD_API_KEY="bk_us1_..."2. Envía un correo electrónico
Envía desde onboarding@messagebird.dev, el dominio compartido de onboarding de Bird, disponible en tu espacio de trabajo sin configuración. Dirígelo a delivered@messagebird.dev, un destinatario de sandbox que siempre entrega, de modo que el resultado es determinista sin un buzón real.
La llamada cURL usa el host de EE. UU. Si tu clave empieza con bk_eu1_, llama a https://eu1.platform.bird.com en su lugar. El SDK lee la región de tu clave y selecciona el host. La pestaña TypeScript requiere 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>"
}'Para los pasos completos de instalación y ejecución en cada lenguaje o framework, usa los quickstarts de SDK.
3. Consulta el resultado
La API responde con 202: Bird ha aceptado el envío para procesamiento asíncrono. Consulta el estado de entrega por separado. Los campos *_count rastrean a los destinatarios a través de los estados de entrega. En la respuesta inicial, un destinatario está aceptado y ninguno está entregado.
Ejemplo de código
{
"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"
}Consulta el mensaje por su ID de em_ para ver su estado actual. Un mensaje pasa de accepted a processed y luego a delivered. Haz polling hasta que el mensaje de sandbox alcance delivered:
const msg = await bird.email.get("em_abc123");
msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
msg.delivered_count;
msg.bounced_count;message = client.email.get("em_abc123")
print(message.id, message.status, message.delivered_count)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)
}$message = $bird->email->get('em_01krdgeqcxet5s7t44vh8rt9mg');
echo $message->getStatus();bird email get <message-id>curl -X GET "https://{region}.platform.bird.com/v1/email/messages/{message_id}" \
-H "Authorization: Bearer $TOKEN"En la pestaña cURL, reemplaza {region} y {message_id}, y usa $BIRD_API_KEY en lugar de $TOKEN.
La lectura ahora muestra status: "delivered", delivered_count: 1 y una marca de tiempo delivered_at. Consulta la guía de eventos para saber qué establece delivered para un destinatario real.
Como enviaste a delivered@messagebird.dev, el resultado está garantizado: el mensaje pasa por el pipeline de entrega real de Bird, incluidos los formatos de eventos y webhooks de producción, pero nunca llega a un buzón real. Para probar un rebote, envía a bounce@messagebird.dev. La guía del sandbox de pruebas lista todas las direcciones de sandbox y su resultado simulado.
Sobre el dominio de onboarding
El remitente compartido onboarding@messagebird.dev está disponible para onboarding y tiene estos límites:
- Aparte de las direcciones de sandbox @messagebird.dev, solo entrega a miembros verificados de tu espacio de trabajo; cualquier otro destinatario se rechaza con un 422.
- Los envíos están limitados a 50 destinatarios por organización por día UTC, contando cada dirección to, cc y bcc, incluidos los destinatarios de sandbox. Superado el límite, la API devuelve un 429.
Cuando estés listo para enviar correos a clientes reales, verifica tu propio dominio de envío y pon tu propia dirección en from; todo lo demás en la solicitud queda igual.
Próximos pasos
- Quickstarts por SDK: el mismo flujo en tu lenguaje y framework.
- Dominios de envío: verifica tu propio dominio para envío en producción.
- Sandbox de pruebas: todas las direcciones de sandbox y los eventos que generan.
- Referencia de API de email: el esquema completo de solicitud y respuesta.
- Primeros pasos con el email: un video del onboarding en el dashboard, que va más allá de esta página y añade un dominio de envío con sus registros DNS
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Comprender el conceptoShould I use a Bird SDK or call the API directly?Explorar la funcionalidadEmailSeguir la ruta de aprendizajeBuild your first integration
Prueba el ejercicio y obtén un resumen de implementación