Anexos

Anexe arquivos a um envio adicionando um array attachments ao payload POST /v1/email/messages. Cada entrada contém os bytes do arquivo codificados em base64 em content, além de um filename. O mesmo array funciona em um item de lote. Os schemas completos de solicitação e resposta estão na referência da API.

Um envio com um anexo

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

client.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",
        }
    ],
)

_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Your invoice",
	HTML:    "<p>Thanks for your order. Your invoice is attached.</p>",
	Attachments: []bird.EmailAttachment{{
		Filename:    "invoice.pdf",
		Content:     pdfBytes,
		ContentType: bird.String("application/pdf"),
	}},
})

$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: [
        (new EmailAttachment())
            ->setFilename('invoice.pdf')
            ->setContent('JVBERi0xLjcKJ...')
            ->setContentType('application/pdf'),
    ],
);

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>' \
  --attach ./invoice.pdf

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": "Your invoice",
    "html": "<p>Thanks for your order. Your invoice is attached.</p>",
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjcKJ...",
        "content_type": "application/pdf"
      }
    ]
  }'

O CLI lê o arquivo e faz a codificação base64 para você; pela API você fornece os bytes codificados diretamente. O SDK de Go recebe os bytes brutos e os codifica no envio.

content são os bytes brutos do arquivo, codificados em base64. content_type é opcional: quando você o omite, inferimos o tipo MIME a partir da extensão de filename, usando application/octet-stream como fallback para extensões não reconhecidas. Todo o restante do envio funciona exatamente como em enviar e-mail: o 202, o modelo assíncrono, tags e metadados não são alterados pela presença de anexos.

Os campos do anexo

Campo	Tipo	Obrigatório	Observações
filename	string	sim	1 a 255 caracteres; exibido ao destinatário. Sem quebras de linha ou caracteres de controle.
content	string	sim	Bytes do arquivo codificados em Base64.
content_type	string	não	Tipo MIME; inferido a partir da extensão do nome do arquivo quando omitido.
content_id	string	não	1 a 128 caracteres, [A-Za-z0-9._-]. Defina-o para renderizar o arquivo inline em vez de anexado.

Um e-mail pode ter até 20 anexos (attachments é limitado a 20 itens).

Imagens inline

Para incorporar uma imagem no corpo HTML em vez de anexá-la, atribua ao anexo um content_id e referencie-o no markup com uma URL cid::

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

O content_id é a ligação entre a referência cid: e o anexo. Cada imagem inline precisa de um content_id único dentro do envio; uma duplicata é rejeitada com um 422. Um anexo sem content_id é entregue como anexo de arquivo comum.

Limite de tamanho

Rejeitamos um envio cujo tamanho estimado da mensagem gerada exceda 20 MB com um 413. A estimativa é o corpo HTML mais o corpo de texto mais todos os anexos medidos após a codificação base64. A codificação infla os bytes brutos em aproximadamente 4/3, então um arquivo de 15 MB já consome sozinho todo o limite de 20 MB. Como regra prática, mantenha o conteúdo total bruto dos anexos bem abaixo de 15 MB para que os corpos e o encapsulamento MIME ainda caibam.

Servidores de recebimento podem aplicar limites de tamanho menores. Uma mensagem que Bird aceita ainda pode ser devolvida se o servidor do destinatário rejeitar o tamanho. Escolha tamanhos de anexo adequados aos provedores de caixa de entrada e organizações para os quais você envia.

Para mensagens recebidas, consulte Tamanho de mensagem de entrada.

Tipos de arquivo bloqueados

Anexos executáveis e de script são rejeitados no momento da validação com um 422, com base no content_type ou na extensão do nome do arquivo. Extensões bloqueadas incluem .exe, .dll, .msi, .bat, .cmd, .scr, .jar, .js, .vbs, .ps1, .sh, .hta e .lnk. Tipos MIME equivalentes como application/x-msdownload, application/java-archive e text/javascript também são bloqueados. Essa validação não é um antivírus. Para distribuir um arquivo bloqueado, hospede-o atrás de um link.

Em um lote

Cada item em um envio em lote pode ter seu próprio attachments, com o mesmo contrato de campos e o mesmo limite de 20 MB por mensagem. O corpo serializado da solicitação do lote tem seu próprio limite adicional, que anexos codificados em base64 consomem rapidamente; consulte envio em lote para o limite do lote e como dividir em torno dele.

Leitura e download de anexos

Leituras de API nunca retornam os bytes do anexo. GET /v1/email/messages/{message_id} retorna um array attachments apenas com metadados; cada entrada contém o id, filename, content_type, size (bytes decodificados) e inline do anexo:

Exemplo de código

{
  "attachments": [
    {
      "id": "ea_019c...",
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "size": 215432,
      "inline": false
    }
  ]
}

Para obter os bytes brutos de volta, chame GET /v1/email/messages/{message_id}/attachments/{attachment_id} (referência). Ele transmite o arquivo com seu próprio content type e um header Content-Disposition contendo o nome do arquivo. Duas condições são necessárias:

O armazenamento de conteúdo deve estar habilitado para o espaço de trabalho. Com o armazenamento desabilitado, nada é armazenado para download. Consulte o que um 202 significa.
Anexos são retidos por 30 dias após o envio. Depois disso, o download retorna 410 Gone.

Um 404 significa que a mensagem não tem conteúdo armazenado ou não tem um anexo com esse ID; um 425 Too Early significa que o anexo ainda está sendo armazenado e a solicitação pode ser tentada novamente em instantes.

Próximos passos

Enviar e-mail: o restante do payload de envio, incluindo destinatários, conteúdo, tags e o modelo assíncrono
Envio em lote: lotes e como os anexos se encaixam em várias mensagens
Referência da API: criar uma mensagem: o schema completo da solicitação, incluindo attachments
Referência da API: baixar um anexo: o endpoint de recuperação e seus códigos de status

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaGetting started with email Explore a funcionalidadeEmail Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first email

Experimente na prática e obtenha um resumo de implementação