View a markdown version of this page

Como trabalhar com anexos de e-mail no SES - Amazon Simple Email Service
Como funcionam os anexosEstrutura de objeto de anexoPráticas recomendadasTipos de anexos incompatíveis

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Como trabalhar com anexos de e-mail no SES

Os anexos de e-mail no SES são arquivos que você pode incluir em suas mensagens de e-mail ao usar as operações SendEmail e SendBulkEmail da API v2 do SES. Esse recurso permite que você enriqueça o conteúdo do seu e-mail ao incluir documentos como PDFs, arquivos do Word, imagens ou outros tipos de arquivo que estejam em conformidade com os tipos MIME compatíveis com o SES. Você também pode incluir imagens em linha que são renderizadas diretamente no conteúdo do e-mail sem exigir que os destinatários as baixem separadamente. É possível incluir vários anexos por e-mail, até o limite total do tamanho da mensagem de 40 MB.

nota

A operação SendEmail da API v2 do SES com tipo de conteúdo Raw, interface SMTP e API v1 do SES continuam lidando com anexos por meio da construção de mensagens MIME de e-mail bruto.

Como funcionam os anexos no SES

Há dois tipos diferentes de codificação que ocorrem em estágios diferentes ao enviar um e-mail com anexos:

Etapa 1: envio de dados para o SES

  • Quando você deseja enviar um anexo para o SES, os dados binários (como um PDF ou imagem) precisam ser convertidos em um formato que possa ser transmitido com segurança.

  • É aqui que entra a codificação base64. Ela é necessária porque não é possível enviar dados binários brutos em uma solicitação JSON.

  • Se você estiver usando o AWS SDK, ele manipula essa codificação automaticamente.

  • Se você estiver usando o AWS CLI, você mesmo precisará codificar o anexo em base64 antes de enviá-lo.

Etapa 2: criação do e-mail pelo SES

  • Depois que o SES recebe seus dados, ele precisa criar um e-mail real com o anexo.

  • É aqui que a ContentTransferEncodingconfiguração entra em jogo.

  • O SES usará qualquer método de codificação especificado ContentTransferEncoding para formatar automaticamente o anexo no e-mail final.

Pense em algo semelhante a enviar um pacote pelo correio. Primeiro, você precisa levar o pacote ao correio (Estágio 1 - Base64-encoding obrigatório) e, em seguida, o correio o empacotará adequadamente para entrega final (Etapa 2 - ContentTransferEncoding).

Estrutura de objeto de anexo

Quando você envia um e-mail com anexos por meio do SES, o serviço processa automaticamente a complexa construção de mensagens MIME. Você só precisa fornecer o conteúdo e os metadados do anexo por meio da seguinte estrutura de objeto Attachment da API v2 do SES:

  • FileName (obrigatório): o nome do arquivo exibido aos destinatários (deve incluir a extensão do arquivo). Se não for fornecido, o SES derivará um ContentType da extensão do FileName.

  • ContentType(Opcional) — identificador do tipo de IANA-compliant mídia.

  • ContentDisposition (opcional): especifica como o anexo deve ser renderizado: ATTACHMENT (padrão) ou INLINE.

  • ContentDescription (opcional): breve descrição do conteúdo.

  • RawContent (obrigatório): o conteúdo real do anexo.

  • ContentTransferEncoding (opcional): especifica como a carga útil do anexo é codificada quando é montada na mensagem MIME do e-mail: SEVEN_BIT (padrão), BASE64 ou QUOTED_PRINTABLE.

Todo o conteúdo anexado deve ser codificado em base64 antes de ser transferido para o endpoint do SES para envio. Se você estiver usando o cliente AWS SDK para fazer chamadas de API, isso será feito automaticamente para você. Se você estiver usando o AWS CLI, ou tiver implementado seu próprio cliente, você mesmo terá que fazer a codificação, como:

  • Conteúdo de texto simples: Text attachment sample content.

  • Codificação base64: VGV4dCBhdHRhY2htZW50IHNhbXBsZSBjb250ZW50Lg==

Os exemplos a seguir mostram como usar a estrutura do objeto anexo ao especificar anexos com a API SES v2 SendEmaile SendBulkEmailoperações usando a AWS CLI referência a um arquivo JSON contendo elementos do objeto anexo.

exemplo— SendEmail com conteúdo simples
aws sesv2 send-email --cli-input-json file://request-send-email-simple.json

request-send-email-simple.json

{
    "FromEmailAddress": "sender@example.com",
    "Destination": {
        "ToAddresses": [
            "recipient@example.com"
        ]
    },
    "Content": {
        "Simple": {
            "Subject": {
                "Data": "Email with attachment"
            },
            "Body": {
                "Text": {
                    "Data": "Please see attached document."
                },
                "Html": {
                    "Data": "Please see attached <b>document</b>."
                }
            },
            "Attachments": [
                {
                    "RawContent": "<base64-encoded-content>",
                    "ContentDisposition": "ATTACHMENT",
                    "FileName": "document.pdf",
                    "ContentDescription": "PDF Document Attachment",
                    "ContentTransferEncoding": "BASE64"
                }
            ]
        }
    }
}
exemplo— SendEmail com conteúdo simples e anexo embutido
aws sesv2 send-email --cli-input-json file://request-send-email-simple-inline-attachment.json

request-send-email-simple-inline-attachment.json

{
    "FromEmailAddress": "sender@example.com",
    "Destination": {
        "ToAddresses": [
            "recipient@example.com"
        ]
    },
    "Content": {
        "Simple": {
            "Subject": {
                "Data": "Email with attachment"
            },
            "Body": {
                "Html": {
                    "Data": "<html><body>Our logo:<br><img src=\"cid:logo123\" alt=\"Company Logo\"></body></html>"
                }
            },
            "Attachments": [
                {
                    "RawContent": "<base64-encoded-content>",
                    "ContentDisposition": "INLINE",
                    "FileName": "logo.png",
                    "ContentId": "logo123",
                    "ContentTransferEncoding": "BASE64"
                }
            ]
        }
    }
}
exemplo— SendEmail com conteúdo do modelo
aws sesv2 send-email --cli-input-json file://request-send-email-template.json

request-send-email-template.json

{
    "FromEmailAddress": "sender@example.com",
    "Destination": {
        "ToAddresses": [
            "recipient@example.com"
        ]
    },
    "Content": {
        "Template": {
            "TemplateName": "MyTemplate",
            "TemplateData": "{\"name\":\"John\"}",
            "Attachments": [
                {
                    "RawContent": "<base64-encoded-content>",
                    "ContentDisposition": "ATTACHMENT",
                    "FileName": "document.pdf",
                    "ContentDescription": "PDF Document Attachment",
                    "ContentTransferEncoding": "BASE64"
                }
            ]
        }
    }
}
exemplo— SendBulkEmail com conteúdo anexo
aws sesv2 send-bulk-email --cli-input-json file://request-send-bulk-email.json

request-send-bulk-email.json

{
    "FromEmailAddress": "sender@example.com",
    "DefaultContent": {
        "Template": {
            "TemplateName": "MyTemplate",
            "TemplateData": "{}",
            "Attachments": [
                {
                    "RawContent": "<base64-encoded-content>",
                    "ContentDisposition": "ATTACHMENT",
                    "FileName": "document.pdf",
                    "ContentDescription": "PDF Document Attachment",
                    "ContentTransferEncoding": "BASE64"
                }
            ]
        }
    },
    "BulkEmailEntries": [
        {
            "Destination": {
                "ToAddresses": [
                    "recipient@example.com"
                ]
            },
            "ReplacementEmailContent": {
                "ReplacementTemplate": {
                    "ReplacementTemplateData": "{\"name\":\"John\"}"
                }
            }
        }
    ]
}

Práticas recomendadas

  • Mantenha o tamanho total da mensagem (incluindo anexos) abaixo de 40 MB.

  • Permita que o SES detecte automaticamente os tipos de conteúdo com base nas extensões de arquivo, quando possível.

  • Especifique explicitamente os tipos de conteúdo somente quando eles estiverem fora dos tipos MIME comuns.

  • Considere o uso de imagens em linha para melhorar a renderização de e-mails.

  • O SES oferece suporte a uma ampla variedade de tipos MIME para anexos, exceto aqueles listados em Tipos de anexos incompatíveis.

Tipos de anexo incompatíveis com o SES

Você pode enviar mensagens com anexos por meio do Amazon SES usando o padrão Multipurpose Internet Mail Extensions (MIME). O Amazon SES aceita todos os tipos de anexos de arquivos, exceto anexos com as extensões de arquivo na lista a seguir.

.ade

.adp

.app

.asp

.bas

.bat

.cer

.chm

.cmd

.com

.cpl

.crt

.csh

.der

.exe

.fxp

.gadget

.hlp

.hta

.inf

.ins

.isp

.its

.js

.jse

.ksh

.lib

.lnk

.mad

.maf

.mag

.mam

.maq

.mar

.mas

.mat

.mau

.mav

.maw

.mda

.mdb

.mde

.mdt

.mdw

.mdz

.msc

.msh

.msh1

.msh2

.mshxml

.msh1xml

.msh2xml

.msi

.msp

.mst

.ops

.pcd

.pif

.plg

.prf

.prg

.reg

.scf

.scr

.sct

.shb

.shs

.sys

.ps1

.ps1xml

.ps2

.ps2xml

.psc1

.psc2

.tmp

.url

.vb

.vbe

.vbs

.vps

.vsmacros

.vss

.vst

.vsw

.vxd

.ws

.wsc

.wsf

.wsh

.xnk

Alguns ISPs têm outras restrições (como restrições relativas a anexos arquivados), por isso, recomendamos testar o envio de e-mails usando os principais ISPs antes de enviar e-mails de produção.