Anexos

Esta página mostra como anexar arquivos aos e-mails que você envia com POST /emails, como conteúdo codificado em base64 ou deixando o Emailit baixá-los de uma URL. Ela também trata de imagens inline, tipos de arquivo permitidos e limites de tamanho.

Campos do anexo

Passe um array attachments. Cada item é um objeto com estes campos:

Anexar um arquivo em base64

Leia o arquivo, codifique-o em base64 e envie-o com o tipo MIME dele.

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',
    ]],
]);

Anexar um arquivo a partir de uma URL

Em vez de codificar o arquivo você mesmo, informe uma url ao Emailit. O Emailit baixa o arquivo enquanto monta a mensagem, então a requisição demora o mesmo tempo que o download.

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

A URL precisa atender a estas regras, senão a requisição falha com 422 e Attachment error:

• Ela usa http ou https e aponta para um host público. Endereços privados e internos são recusados.
• Ela retorna o arquivo diretamente, com um status 2xx. Redirecionamentos não são seguidos.
• O download termina em até 30 segundos.
• O arquivo não tem mais de 25 MB, conforme informado pelo cabeçalho Content-Length dele.

O Emailit monta uma cópia separada da mensagem para cada destinatário e baixa os anexos por URL para cada cópia. Garanta que URLs assinadas ou com validade continuem válidas durante toda a requisição e que o servidor dos arquivos aguente um download por destinatário.

Incorporar imagens inline

Para exibir uma imagem dentro do corpo HTML em vez de como um anexo separado, dê a ela um content_id e faça referência a esse ID com cid: em uma tag 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"
    }
  ]
}

O content_id do anexo e o valor depois de cid: devem ser exatamente iguais. Imagens inline deixam a mensagem maior para cada destinatário, então, para logotipos e outras imagens compartilhadas, uma URL de imagem hospedada no HTML costuma ser a melhor escolha.

Limites de tamanho

A codificação base64 deixa os arquivos cerca de um terço maiores, e o limite de 40 MB vale para a mensagem codificada. Na prática, mantenha o tamanho somado dos seus arquivos abaixo de uns 29 MB. Para qualquer coisa maior, envie o arquivo para o seu próprio armazenamento e mande um link.

Tipos de arquivo permitidos

filename deve terminar com uma destas extensões. Qualquer outra extensão, ou um nome sem extensão, falha na validação com 400.

Arquivos executáveis e scripts não estão na lista e não podem ser anexados.

Ler os anexos de um e-mail enviado

Listar anexos (GET /emails/{id}/attachments) retorna cada anexo com filename, content_type, size, content_id, content_disposition (attachment ou inline) e o content em base64. É preciso uma chave Full Access. Os anexos são excluídos junto com o conteúdo da mensagem quando termina o seu período de retenção de dados.

Solução de problemas

Veja também

• Enviar um e-mail
• Enviar um e-mail na referência da API
• Retenção de dados