Adjuntos

Esta página muestra cómo adjuntar archivos a los emails que envías con POST /emails, ya sea como contenido codificado en base64 o dejando que Emailit los descargue desde una URL. También trata las imágenes en línea, los tipos de archivo permitidos y los límites de tamaño.

Campos de los adjuntos

Pasa un array attachments. Cada elemento es un objeto con estos campos:

Adjuntar un archivo en base64

Lee el archivo, codifícalo en base64 y envíalo con su tipo MIME.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"Acme Billing <billing@acme.com>\",
    \"to\": \"ada@example.com\",
    \"subject\": \"Invoice INV-1042\",
    \"text\": \"Your invoice is attached.\",
    \"attachments\": [{
      \"filename\": \"INV-1042.pdf\",
      \"content\": \"$(base64 < INV-1042.pdf | tr -d '\n')\",
      \"content_type\": \"application/pdf\"
    }]
  }"

import { readFile } from 'node:fs/promises';
import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);
const pdf = await readFile('INV-1042.pdf');

await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: 'ada@example.com',
  subject: 'Invoice INV-1042',
  text: 'Your invoice is attached.',
  attachments: [
    {
      filename: 'INV-1042.pdf',
      content: pdf.toString('base64'),
      content_type: 'application/pdf',
    },
  ],
});

import base64
import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

with open("INV-1042.pdf", "rb") as f:
    pdf = base64.b64encode(f.read()).decode("ascii")

client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": "ada@example.com",
    "subject": "Invoice INV-1042",
    "text": "Your invoice is attached.",
    "attachments": [{
        "filename": "INV-1042.pdf",
        "content": pdf,
        "content_type": "application/pdf",
    }],
})

$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => 'ada@example.com',
    'subject' => 'Invoice INV-1042',
    'text' => 'Your invoice is attached.',
    'attachments' => [[
        'filename' => 'INV-1042.pdf',
        'content' => base64_encode(file_get_contents('INV-1042.pdf')),
        'content_type' => 'application/pdf',
    ]],
]);

Adjuntar un archivo desde una URL

En lugar de codificar tú el archivo, dale a Emailit una url. Emailit descarga el archivo mientras construye el mensaje, así que la petición tarda lo mismo que la descarga.

{
  "from": "Acme Billing <billing@acme.com>",
  "to": "ada@example.com",
  "subject": "Invoice INV-1042",
  "text": "Your invoice is attached.",
  "attachments": [
    {
      "filename": "INV-1042.pdf",
      "url": "https://files.acme.com/invoices/INV-1042.pdf"
    }
  ]
}

La URL tiene que cumplir estas reglas; si no, la petición falla con 422 y Attachment error:

• Usa http o https y apunta a un host público. Las direcciones privadas e internas se rechazan.
• Devuelve el archivo directamente con un estado 2xx. No se siguen las redirecciones.
• La descarga termina en 30 segundos como máximo.
• El archivo no ocupa más de 25 MB, según su cabecera Content-Length.

Emailit construye una copia distinta del mensaje para cada destinatario y descarga los adjuntos por URL para cada copia. Asegúrate de que las URL firmadas o con caducidad sigan siendo válidas durante toda la petición, y de que el servidor de archivos pueda soportar una descarga por destinatario.

Insertar imágenes en línea

Para mostrar una imagen dentro del cuerpo HTML en lugar de como un adjunto aparte, dale un content_id y haz referencia a ese ID con cid: en una etiqueta img.

{
  "from": "Acme <hello@acme.com>",
  "to": "ada@example.com",
  "subject": "Your weekly report",
  "html": "<p><img src=\"cid:chart-week-40\" alt=\"Weekly signups\" width=\"600\"></p>",
  "attachments": [
    {
      "filename": "chart.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAA...",
      "content_type": "image/png",
      "content_id": "chart-week-40"
    }
  ]
}

El content_id del adjunto y el valor que sigue a cid: deben coincidir exactamente. Las imágenes en línea hacen más grande el mensaje para cada destinatario, así que para los logotipos y otras imágenes compartidas suele ser mejor opción una URL de imagen alojada en el HTML.

Límites de tamaño

La codificación base64 hace que los archivos ocupen aproximadamente un tercio más, y el límite de 40 MB se aplica al mensaje codificado. En la práctica, mantén el tamaño total de tus archivos por debajo de unos 29 MB. Para cualquier cosa más grande, sube el archivo a tu propio almacenamiento y envía un enlace.

Tipos de archivo permitidos

filename debe terminar en una de estas extensiones. Cualquier otra extensión, o un nombre sin extensión, no supera la validación y devuelve 400.

Los archivos ejecutables y los scripts no están en la lista y no se pueden adjuntar.

Leer los adjuntos de un email enviado

Listar adjuntos (GET /emails/{id}/attachments) devuelve cada adjunto con su filename, content_type, size, content_id, content_disposition (attachment o inline) y su content en base64. Necesita una clave Full Access. Los adjuntos se eliminan junto con el contenido del mensaje cuando termina tu periodo de retención de datos.

Solución de problemas

Ver también

• Enviar un email
• Referencia de la API: Enviar un email
• Retención de datos