Enviar correo electrónico

Un envío mínimo

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

Enviar antes de verificar un dominio

Construir el payload

Destinatarios

Contenido

Reply-to y encabezados personalizados

• Encabezados de direccionamiento y plataforma. Configura el direccionamiento del mensaje a través de los campos dedicados (from, to, cc, bcc, reply_to, subject). Esos nombres, y los encabezados que generamos por ti (Content-Type, Content-Transfer-Encoding, DKIM-Signature, Received, Return-Path), no se pueden establecer aquí.
• List-Unsubscribe y List-Unsubscribe-Post en un envío marketing. Nosotros establecemos un encabezado de cancelación de suscripción con un clic conforme en esos envíos. En un envío transactional dejamos los tuyos exactamente como los configuraste.
• Cualquier valor con un retorno de carro o salto de línea.

Seguimiento

Categoría y pool de IP

Referencia de campos

Enviar con una plantilla

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 plantilla, nunca ambos. Enviar template junto con subject, html o text se rechaza con un 422. El API también rechaza valores de variables en el campo de nivel superior parameters; en un envío con plantilla pertenecen a template.parameters.
• bird es el único nombre reservado. Una ruta de marcador de posición que comienza con bird. nombra nuestros propios datos, como el enlace de cancelación de suscripción o el registro de contacto del destinatario, por lo que una clave template.parameters no puede llamarse bird. Todas las demás claves las defines tú, y cada una es una sola palabra: {"order_number": "A-1043"} rellena {{ order_number }}.
• Una plantilla se puede enviar ahora o después. Añade scheduled_at para programar el envío. Fijamos la versión publicada, el idioma seleccionado y los valores de los parámetros en el momento de la aceptación. Si eliminas la plantilla antes de la hora de envío, el mensaje se rechaza con generation_failure.
• Un envío usa la versión publicada de la plantilla. Los borradores nunca se envían. Una plantilla desconocida se rechaza con un 404, y una plantilla sin versión publicada con un 422.
• language selecciona uno de los idiomas de la plantilla. Omítelo para enviar el idioma predeterminado de la plantilla. Si pides uno que la plantilla no tiene, su propia configuración on_missing_language decide si se envía la coincidencia más cercana o se rechaza el envío. Una plantilla que establece language_source_required rechaza un envío que no nombre ningún idioma.
• La categoría de la plantilla es un valor predeterminado, y la tuya lo sobrescribe. Omite category y el envío hereda la de la plantilla, así que una plantilla transaccional no necesita repetirla en cada llamada.

Tags vs metadata

• tags son pares {name, value} estructurados: hasta 20 por envío, nombre de hasta 32 caracteres, valor de hasta 64, solo letras ASCII, dígitos, guion bajo y guion, y nombres únicos dentro del envío. Los tags son dimensiones de filtro, así que puedes filtrar la lista de mensajes por tag y segmentar analíticas y resúmenes de dashboard por tag. Úsalos para etiquetas de baja cardinalidad como campaign, experiment_variant o source.
• metadata es un objeto JSON arbitrario, de hasta 2 KB serializados. Lo almacenamos, lo devolvemos en lecturas API y lo incluimos en cada evento de webhook, así que es adecuado para contexto que quieres que te devolvamos: IDs internos, claves foráneas, payloads estructurados.

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

Adjuntos

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

• Las lecturas devuelven el estado sin el cuerpo. GET /v1/email/messages/{message_id} devuelve el estado del mensaje y del destinatario, nunca el cuerpo html o text. Cuando el almacenamiento de contenido está habilitado en el espacio de trabajo, los cuerpos almacenados permanecen disponibles hasta 30 días desde GET /v1/email/messages/{message_id}/content.
• Una lectura puede ir brevemente detrás del envío. Un 404 en los endpoints de lectura justo después de un 202 significa que el mensaje aún no es visible, así que reintenta en un momento.

Reintentar de forma segura

Envío en lote

Facturación

Próximos pasos

• Plantillas de correo: crea y publica las plantillas que envías aquí
• Categorías: cómo marketing y transactional cambian el comportamiento de supresión
• Supresiones: a quién no entregamos y por qué
• Envío programado: entrega en un momento futuro con scheduled_at
• Sandbox de pruebas: destinatarios sandbox y envío previo a la verificación
• Referencia de API: los esquemas completos de solicitud y respuesta