Envía tu primer correo electrónico
Crea una clave de API, envía a través del dominio de incorporación compartido de Bird y consulta el resultado. Para esta guía no necesitas verificar un dominio de envío ni publicar registros DNS. Verifica tu propio dominio antes de enviar correos a clientes.
1. Crea una clave de API
En el panel, ve a Platform tools > API keys y crea una clave. Cada clave pertenece a una región y tiene el formato bk_us1_... o bk_eu1_.... La región del prefijo indica a qué host de API debes llamar: https://us1.platform.bird.com o https://eu1.platform.bird.com.

La clave completa se muestra una sola vez, al crearla. Cópiala en un lugar seguro y luego expórtala para que los fragmentos de código del paso 2 puedan leerla:
export BIRD_API_KEY="bk_us1_..."2. Envía un correo electrónico
Envía desde onboarding@messagebird.dev, el dominio de incorporación compartido de Bird, disponible en tu espacio de trabajo sin ninguna configuración. Dirígelo a delivered@messagebird.dev, un destinatario de prueba que siempre recibe la entrega, para que el resultado sea predecible sin necesidad de un buzón real.
La llamada de cURL usa el host de EE. UU. Si tu clave empieza por bk_eu1_, llama a https://eu1.platform.bird.com. SDK lee la región de tu clave y elige el host. La pestaña de 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 ver los pasos completos de instalación y ejecución en cada lenguaje o framework, consulta las guías de inicio rápido de SDK.
3. Consulta el resultado
La API responde con 202: Bird ha aceptado el envío para procesarlo de forma asíncrona. Consulta el estado de entrega por separado. Los campos *_count registran a los destinatarios a lo largo de los estados de entrega. En la respuesta inicial, hay un destinatario aceptado y ninguno entregado.
{
"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"
}Obtén el mensaje por su ID de em_ para ver su estado actual. Un mensaje pasa de accepted a processed y después a delivered. Consulta periódicamente hasta que el mensaje de sandbox llegue a 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"En la pestaña de cURL, sustituye {region} y {message_id}, y usa $BIRD_API_KEY en lugar de $TOKEN.
La lectura muestra ahora status: "delivered", delivered_count: 1 y una marca de tiempo delivered_at. Consulta la guía de eventos para saber qué garantiza delivered con un destinatario real.
Como enviaste a delivered@messagebird.dev, el resultado está garantizado: el mensaje recorre la canalización 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 enumera todas las direcciones de sandbox y el resultado que simula cada una.
Acerca del dominio de incorporación
El remitente compartido onboarding@messagebird.dev está disponible para la incorporación y tiene estos límites:
- Aparte de las direcciones de sandbox de
@messagebird.dev, solo entrega a miembros verificados de tu espacio de trabajo; cualquier otro destinatario se rechaza con un422. - Los envíos están limitados a 50 destinatarios por organización y día UTC, contando cada dirección de
to,ccybcc, incluidos los destinatarios de sandbox. Al superar el límite, la API devuelve un429.
Cuando quieras enviar correos a clientes reales, verifica tu propio dominio de envío y pon tu propia dirección en from; el resto de la solicitud no cambia.
Próximos pasos
- Guías de inicio rápido por SDK: el mismo flujo en tu lenguaje y framework.
- Dominios de envío: verifica tu propio dominio para enviar en producción.
- Sandbox de pruebas: todas las direcciones del sandbox y los eventos que generan.
- Referencia de la API de email: el esquema completo de la solicitud y la respuesta.
- Primeros pasos con el email: un vídeo de la incorporación 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 de este tema.