Sign inGet Started

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 página API Keys del panel de Bird, con la lista de claves, su prefijo enmascarado, sus permisos y la hora del último uso

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:

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

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.

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

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

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 un 422.
  • Los envíos están limitados a 50 destinatarios por organización y día UTC, contando cada dirección de to, cc y bcc, incluidos los destinatarios de sandbox. Al superar el límite, la API devuelve un 429.

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