Documentación
Sign inGet started
Comenzar
Guías
Referencia de API
SDKs
CLI
Base de conocimientos
Registro de cambios

Archivos adjuntos

Adjunta archivos a un envío añadiendo un array attachments al payload de POST /v1/email/messages. Cada entrada contiene los bytes del archivo codificados en base64 en content, más un filename. El mismo array funciona en un elemento de lote. Los esquemas completos de solicitud y respuesta están en la referencia de API.

Un envío con un archivo adjunto

await bird.email.send({
  from: "hello@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Your invoice",
  html: "<p>Thanks for your order. Your invoice is attached.</p>",
  attachments: [
    {
      filename: "invoice.pdf",
      content: "JVBERi0xLjcKJ...",
      content_type: "application/pdf",
    },
  ],
});
El CLI lee el archivo y lo codifica en base64 por ti; con la API proporcionas los bytes codificados tú mismo. El SDK de Go toma los bytes sin procesar y los codifica en el envío.
content son los bytes sin procesar del archivo, codificados en base64. content_type es opcional: cuando lo omites, inferimos el tipo MIME a partir de la extensión de filename, usando application/octet-stream como valor por defecto para extensiones que no reconocemos. Todo lo demás del envío funciona exactamente como en enviar correo electrónico: el 202, el modelo asíncrono, las etiquetas y los metadatos no cambian por la presencia de archivos adjuntos.

Campos del archivo adjunto

CampoTipoObligatorioNotas
filenamestringsíDe 1 a 255 caracteres; se muestra al destinatario. Sin saltos de línea ni caracteres de control.
contentstringsíBytes del archivo codificados en Base64.
content_typestringnoTipo MIME; se infiere de la extensión del nombre de archivo cuando se omite.
content_idstringnoDe 1 a 128 caracteres, [A-Za-z0-9._-]. Configúralo para mostrar el archivo en línea en lugar de adjunto.
Un correo electrónico puede tener hasta 20 archivos adjuntos (attachments tiene un máximo de 20 elementos).

Imágenes en línea

Para incrustar una imagen en el cuerpo HTML en lugar de adjuntarla, asigna al adjunto un content_id y haz referencia a él desde el marcado con una URL cid::
Ejemplo de código
{
  "html": "<p>Welcome aboard!</p><img src=\"cid:welcome-banner\"/>",
  "attachments": [
    {
      "filename": "banner.png",
      "content": "iVBORw0KGgoAAAANS...",
      "content_type": "image/png",
      "content_id": "welcome-banner"
    }
  ]
}
El content_id es la unión entre la referencia cid: y el adjunto. Cada imagen en línea necesita un content_id único dentro del envío; un duplicado se rechaza con un 422. Un adjunto sin content_id se entrega como un archivo adjunto normal.

Presupuesto de tamaño

Rechazamos un envío cuyo tamaño estimado del mensaje generado supere 20 MB con un 413. La estimación es el cuerpo HTML más el cuerpo de texto más cada adjunto medido después de la codificación en base64. La codificación infla los bytes sin procesar aproximadamente en un factor de 4/3, así que un archivo de 15 MB ya consume por sí solo todo el presupuesto de 20 MB. Como regla general, mantén el contenido total de adjuntos sin procesar bien por debajo de 15 MB para que los cuerpos y el empaquetado MIME sigan cabiendo.
Los servidores receptores pueden aplicar límites de tamaño más bajos. Un mensaje que Bird acepta aún puede rebotar si el servidor del destinatario rechaza su tamaño. Elige tamaños de adjuntos adecuados para los proveedores de correo y las organizaciones a los que envías.
Para mensajes recibidos, consulta Tamaño de mensaje entrante.

Tipos de archivo bloqueados

Los adjuntos ejecutables y de script se rechazan en el momento de la validación con un 422, basándose en content_type o en la extensión del nombre de archivo. Las extensiones bloqueadas incluyen .exe, .dll, .msi, .bat, .cmd, .scr, .jar, .js, .vbs, .ps1, .sh, .hta y .lnk. Los tipos MIME equivalentes como application/x-msdownload, application/java-archive y text/javascript también están bloqueados. Esta validación no es un antivirus. Para distribuir un archivo bloqueado, alójalo detrás de un enlace.

En un lote

Cada elemento en un envío por lotes puede tener su propio attachments, con el mismo contrato de campos y el mismo presupuesto de 20 MB por mensaje. El cuerpo serializado de la solicitud del lote tiene su propio límite adicional, que los adjuntos codificados en base64 consumen rápidamente; consulta envío por lotes para conocer el límite a nivel de lote y cómo dividir en torno a él.

Lectura y descarga de archivos adjuntos

Las lecturas de API nunca devuelven los bytes del adjunto. GET /v1/email/messages/{message_id} devuelve un array attachments solo con metadatos; cada entrada tiene el id, filename, content_type, size (bytes decodificados) y inline del adjunto:
Ejemplo de código
{
  "attachments": [
    {
      "id": "ea_019c...",
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "size": 215432,
      "inline": false
    }
  ]
}
Para obtener los bytes sin procesar, llama a GET /v1/email/messages/{message_id}/attachments/{attachment_id} (referencia). Transmite el archivo con su propio tipo de contenido y un encabezado Content-Disposition con el nombre del archivo. Dos condiciones lo controlan:
  • El almacenamiento de contenido debe estar habilitado para el espacio de trabajo. Con el almacenamiento deshabilitado, no se guarda nada para descargar. Consulta qué significa un 202.
  • Los archivos adjuntos se conservan durante 30 días después del envío. Después de ese plazo, la descarga devuelve 410 Gone.
Un 404 significa que el mensaje no tiene contenido almacenado o no tiene un adjunto con ese ID; un 425 Too Early significa que el adjunto aún se está almacenando y la solicitud se puede reintentar en un momento.

Próximos pasos

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Ver la guíaGetting started with emailExplorar la funcionalidadEmailSeguir la ruta de aprendizajeBuild your first integrationGuía de implementaciónSend your first email
Prueba el ejercicio y obtén un resumen de implementación