Como usar modelos para enviar e-mails personalizados com a API do Amazon SES - Amazon Simple Email Service
(Opcional) Parte 1: Configurar notificações(Opcional) Parte 2: Criar um modelo de e-mailParte 3: Enviar os e-mails personalizados

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 usar modelos para enviar e-mails personalizados com a API do Amazon SES

No Amazon SES, você pode enviar e-mails com base em modelo usando um modelo armazenado ou usando um modelo em linha.

  • Modelo armazenado: refere-se ao recurso Template que é criado e salvo no SES usando a operação CreateEmailTemplate na API v2 do Amazon SES. O modelo contém o assunto e o corpo do e-mail contendo variáveis (espaços reservados) em linha com o conteúdo escrito. O nome do modelo armazenado e os dados dinâmicos das variáveis de espaço reservado no modelo são fornecidos ao chamar as operações SendEmail ou SendBulkEmail da API v2.

    Os modelos armazenados podem ser facilmente reutilizados e podem economizar tempo e esforço ao enviar tipos semelhantes de e-mails. Em vez de criar cada e-mail do zero, basta criar a estrutura básica e o design uma vez, depois atualizar o conteúdo dinâmico dentro do modelo.

  • Modelo em linha: o recurso Template não é usado. Em vez disso, o assunto e o corpo do e-mail contendo variáveis (espaços reservados) em linha com o conteúdo escrito, além dos valores dessas variáveis de espaço reservado, são fornecidos ao chamar as operações SendEmail ou SendBulkEmail da API v2.

    Os modelos em linha simplificam o processo de envio de e-mails em massa, eliminando a necessidade de gerenciar recursos de modelo em sua conta do SES, e simplificam o processo de integração, permitindo que você inclua o conteúdo do modelo diretamente na lógica da aplicação. Eles não contam contra o limite de 20.000 modelos por.Região da AWS

Os seguintes limites se aplicam ao usar modelos armazenados:

  • Você pode criar até 20.000 modelos de e-mail em cada um Região da AWS.

  • Cada modelo pode ter até 500 KB, incluindo as partes de texto e de HTML.

O limite a seguir se aplica ao usar modelos em linha:

  • Cada arquivo JSON de entrada pode ter até 1 MB, incluindo as partes de texto e HTML.

O seguinte se aplica aos modelos armazenados e embutidos:

  • Não há limites para o número de variáveis de substituição que podem ser usadas.

  • Você pode enviar e-mails para até 50 objetos de destino em cada chamada para a operação SendBulkEmail. O Destinationobjeto pode conter vários destinatários definidos em ToAddressesCcAddresses, e. BccAddresses O número de destinos com os quais você pode entrar em contato em uma única chamada à API v2 pode ser limitado pela taxa máxima de envio da sua conta. Para obter mais informações, consulte Gerenciamento de limites do envio do Amazon SES.

Este capítulo inclui procedimentos com exemplos para usar modelos armazenados e modelos em linha.

nota

Os procedimentos desta seção também pressupõem que você já instalou e configurou a AWS CLI. Para obter mais informações sobre como instalar e configurar o AWS CLI, consulte o Guia do AWS Command Line Interface usuário.

(Opcional) Parte 1: Configurar notificações de eventos de falha de renderização

Se você enviar um e-mail que contenha conteúdo de personalização inválido, o Amazon SES pode até aceitar a mensagem, mas não poderá entregá-la. Por esse motivo, se você planeja enviar e-mails personalizados, configure o SES para enviar notificações de eventos de falha de renderização pelo Amazon SNS. Ao receber uma notificação de evento de Falha de renderização, você pode identificar qual mensagem continha o conteúdo inválido, corrigir os problemas e enviar a mensagem novamente.

O procedimento nesta seção é opcional, mas altamente recomendado.

Para configurar notificações de eventos de Falha de renderização

  1. Crie um tópico do Amazon SNS. Para obter procedimentos, consulte Criar um tópico no Guia do desenvolvedor do Amazon Simple Notification Service.

  2. Assine o tópico do Amazon SNS. Por exemplo, se você quiser receber notificações de Falha de renderização por e-mail, inscreva um endpoint de e-mail (ou seja, seu endereço de e-mail) no tópico.

    Para obter os procedimentos, consulte Assinar um tópico no Guia do desenvolvedor do Amazon Simple Notification Service.

  3. Execute os procedimentos em Configure um destino de eventos do Amazon SNS para publicação de eventos para configurar os conjuntos de configurações para publicação de eventos de falha de processamento no seu tópico sobre o Amazon SNS.

(Opcional) Parte 2: Criar um modelo de e-mail

Se você pretende usar um modelo armazenado, esta seção mostrará como usar a operação CreateEmailTemplate da API v2 do SES para criar o modelo. Você pode pular esta etapa se deseja usar um modelo em linha.

Esse procedimento pressupõe que você já tenha instalado e configurado a AWS CLI. Para obter mais informações sobre como instalar e configurar o AWS CLI, consulte o Guia do AWS Command Line Interface usuário.

Para criar o modelo

  1. Em um editor de texto, crie um arquivo e cole o código a seguir, personalizando-o conforme necessário.

    {
    "TemplateName": "MyTemplate",
    "TemplateContent": {
        "Subject": "Greetings, {{name}}!",
        "Text": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}.",
        "Html": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>"
    }
}

    Esse código contém as seguintes propriedades:

    • TemplateName— O nome do Template recurso. Quando você enviar o e-mail, consulte este nome.

    • TemplateContent— Um contêiner para os seguintes atributos:

      • Assunto: a linha de assunto do e-mail. Essa propriedade pode conter tags de substituição. Essas tags usam o seguinte formato: {{tagname}}. Quando você envia o e-mail, pode especificar um valor para tagname de cada destino.

      • Html: o corpo HTML do e-mail. Essa propriedade pode conter tags de substituição. O exemplo anterior inclui duas tags: {{name}} e {{favoriteanimal}}.

      • Text: o corpo de texto do e-mail. Os destinatários cujos clientes de e-mail não exibem conteúdo HTML verão esta versão do e-mail. Essa propriedade também pode conter tags de substituição.

  2. Personalize o exemplo anterior de acordo com as suas necessidades e salve o arquivo como mytemplate.json.

  3. Na linha de comando, digite o seguinte comando para criar um modelo usando a operação CreateEmailTemplate da API v2:

    aws sesv2 create-email-template --cli-input-json file://mytemplate.json

Parte 3: Enviar os e-mails personalizados

Você pode usar as duas operações da API v2 do SES a seguir para enviar e-mails usando modelos armazenados ou modelos em linha:

  • A operação SendEmail é útil para enviar um e-mail personalizado para um único objeto de destino. O Destinationobjeto da API v2 pode conter as BccAddressespropriedades ToAddressesCcAddresses, e. Elas podem ser usadas em qualquer combinação e podem conter um ou mais endereços de e-mail que receberão o mesmo e-mail.

  • A operação SendBulkEmail é útil para envio de e-mails exclusivos a vários objetos de destino em uma única chamada para a API v2.

Esta seção fornece exemplos de como usar o AWS CLI para enviar e-mails modelados usando essas duas operações de envio.

Enviar e-mails com base em modelo a um único objeto de destino

Você pode usar a operação SendEmail para enviar um e-mail a um ou mais destinatários definidos em um único objeto de destino. Todos os destinatários no objeto Destination receberão o mesmo e-mail.

Como enviar um e-mail com base em modelo a um único objeto de destino

  1. Dependendo se você deseja usar um modelo armazenado ou um modelo em linha, selecione o exemplo de código respectivo para colar em um editor de texto, personalizando-o conforme necessário.

    Stored template code example

    Observe que o modelo que você criou na etapa anterior, MyTemplate, está sendo referenciado como o valor do TemplateName parâmetro.

    {
    "FromEmailAddress": "Mary Major <mary.major@example.com>",
    "Destination": {
        "ToAddresses": [
            "alejandro.rosalez@example.com", "jimmy.jet@example.com"
        ]
    },
    "Content": {
        "Template": {
            "TemplateName": "MyTemplate",
            "TemplateData": "{ \"name\":\"Alejandro\", \"favoriteanimal\": \"alligator\" }"
        }
    },
    "ConfigurationSetName": "ConfigSet"
}

    Esse código contém as seguintes propriedades:

    • FromEmailAddress— O endereço de e-mail do remetente.

    • Destino — Um objeto contendo os destinatários de e-mail definidos nas BccAddressespropriedades ToAddressesCcAddresses, e. Elas podem ser usadas em qualquer combinação e podem conter um ou mais endereços de e-mail que receberão o mesmo e-mail.

    • TemplateName— O nome do Template recurso a ser aplicado ao e-mail.

    • TemplateData— Uma string JSON com escape que contém pares de valores-chave. As chaves correspondem às variáveis definidas nas propriedades TemplateContent do modelo armazenado, por exemplo, {{name}}. Os valores representam o conteúdo que substitui as variáveis.

    • ConfigurationSetName— O nome do conjunto de configurações a ser usado ao enviar o e-mail.

      nota

      Recomendamos que você use um conjunto de configurações definido para publicar eventos de falha de processamento no Amazon SNS. Para obter mais informações, consulte (Opcional) Parte 1: Configurar notificações de eventos de falha de renderização.

    Inline template code example

    Observe que as propriedades TemplateContent (que normalmente seriam definidas em um modelo armazenado) estão sendo definidas em linha, junto com a propriedade TemplateData, o que faz dele um modelo em linha.

    {
    "FromEmailAddress": "Mary Major <mary.major@example.com>",
    "Destination": {
        "ToAddresses": [
            "alejandro.rosalez@example.com", "jimmy.jet@example.com"
        ]
    },
    "Content": {
        "Template": {
            "TemplateContent": {
                "Subject": "Greetings, {{name}}!",
                "Text": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}.",
                "Html": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>"
            },
            "TemplateData": "{ \"name\":\"Alejandro\", \"favoriteanimal\": \"alligator\" }"
        }
    },
    "ConfigurationSetName": "ConfigSet"
}

    Esse código contém as seguintes propriedades:

    • FromEmailAddress— O endereço de e-mail do remetente.

    • Destino — Um objeto contendo os destinatários de e-mail definidos nas BccAddressespropriedades ToAddressesCcAddresses, e. Elas podem ser usadas em qualquer combinação e podem conter um ou mais endereços de e-mail que receberão o mesmo e-mail.

    • TemplateContent— Um contêiner para os seguintes atributos:

      • Assunto: a linha de assunto do e-mail. Essa propriedade pode conter tags de substituição. Essas tags usam o seguinte formato: {{tagname}}. Quando você envia o e-mail, pode especificar um valor para tagname de cada destino.

      • Html: o corpo HTML do e-mail. Essa propriedade pode conter tags de substituição. O exemplo anterior inclui duas tags: {{name}} e {{favoriteanimal}}.

      • Text: o corpo de texto do e-mail. Os destinatários cujos clientes de e-mail não exibem conteúdo HTML verão esta versão do e-mail. Essa propriedade também pode conter tags de substituição.

    • TemplateData— Uma string JSON com escape que contém pares de valores-chave. As chaves correspondem às variáveis definidas nas propriedades TemplateContent desse arquivo, por exemplo, {{name}}. Os valores representam o conteúdo que substitui as variáveis.

    • ConfigurationSetName— O nome do conjunto de configurações a ser usado ao enviar o e-mail.

      nota

      Recomendamos que você use um conjunto de configurações definido para publicar eventos de falha de processamento no Amazon SNS. Para obter mais informações, consulte (Opcional) Parte 1: Configurar notificações de eventos de falha de renderização.

  2. Personalize o exemplo anterior de acordo com as suas necessidades e salve o arquivo como myemail.json.

  3. Na linha de comando, digite o seguinte comando da API v2 para enviar o e-mail:

    aws sesv2 send-email --cli-input-json file://myemail.json

Enviar e-mails com base em modelo a vários objetos de destino

Você pode usar a operação SendBulkEmail para enviar um e-mail a vários objetos de destino em uma única chamada para a API v2 do SES. O SES envia um e-mail exclusivo para os destinatários em cada objeto Destination.

Como enviar um e-mail com base em modelo a vários objetos de destino

  1. Dependendo se você deseja usar um modelo armazenado ou um modelo em linha, selecione o exemplo de código respectivo para colar em um editor de texto, personalizando-o conforme necessário.

    Stored template code example

    Observe que o modelo que você criou na etapa anterior, MyTemplate, está sendo referenciado como o valor do TemplateName parâmetro.

    {
    "FromEmailAddress": "Mary Major <mary.major@example.com>",
    "DefaultContent": {
        "Template": {
            "TemplateName": "MyTemplate",
            "TemplateData": "{ \"name\":\"friend\", \"favoriteanimal\":\"unknown\" }"
        }
    },
    "BulkEmailEntries": [
        {
            "Destination": {
                "ToAddresses": [
                    "anaya.iyengar@example.com"
                ]
            },
            "ReplacementEmailContent": {
                "ReplacementTemplate": {
                    "ReplacementTemplateData": "{ \"name\":\"Anaya\", \"favoriteanimal\":\"angelfish\" }"
                }
            }
        },
        {
            "Destination": {
                "ToAddresses": [
                    "liu.jie@example.com"
                ]
            },
            "ReplacementEmailContent": {
                "ReplacementTemplate": {
                    "ReplacementTemplateData": "{ \"name\":\"Liu\", \"favoriteanimal\":\"lion\" }"
                }
            }
        },
        {
            "Destination": {
                "ToAddresses": [
                    "shirley.rodriguez@example.com"
                ]
            },
            "ReplacementEmailContent": {
                "ReplacementTemplate": {
                    "ReplacementTemplateData": "{ \"name\":\"Shirley\", \"favoriteanimal\":\"shark\" }"
                }
            }
        },
        {
            "Destination": {
                "ToAddresses": [
                    "richard.roe@example.com"
                ]
            },
            "ReplacementEmailContent": {
                "ReplacementTemplate": {
                    "ReplacementTemplateData": "{}"
                }
            }
        }
    ],
    "ConfigurationSetName": "ConfigSet"
}

    Esse código contém as seguintes propriedades:

    • FromEmailAddress— O endereço de e-mail do remetente.

    • DefaultContent— Um objeto JSON que contém os TemplateData objetos TemplateName e.

    • TemplateName— O nome do Template recurso a ser aplicado ao e-mail.

    • TemplateData— Contém pares de valores-chave que serão usados se o ReplacementEmailContent objeto contiver um objeto JSON vazio,{}, na propriedade. ReplacementTemplateData

    • BulkEmailEntries— Uma matriz que contém um ou mais Destination objetos.

    • Destino — Um objeto contendo os destinatários de e-mail definidos nas BccAddressespropriedades ToAddressesCcAddresses, e. Elas podem ser usadas em qualquer combinação e podem conter um ou mais endereços de e-mail que receberão o mesmo e-mail.

    • ReplacementTemplateData— Uma string JSON com escape que contém pares de valores-chave. As chaves correspondem às variáveis do modelo, por exemplo, {{name}}. Os valores representam o conteúdo que substitui as variáveis no e-mail. (Se a string JSON aqui estiver vazia, indicada por {}, os pares de chave-valor definidos na propriedade TemplateData dentro do objeto DefaultContent serão usados.)

    • ConfigurationSetName— O nome do conjunto de configurações a ser usado ao enviar o e-mail.

      nota

      Recomendamos que você use um conjunto de configurações definido para publicar eventos de falha de processamento no Amazon SNS. Para obter mais informações, consulte (Opcional) Parte 1: Configurar notificações de eventos de falha de renderização.

    Inline template code example

    Observe que as propriedades TemplateContent (que normalmente seriam definidas em um modelo armazenado) estão sendo definidas em linha, junto com a propriedade TemplateData, o que faz dele um modelo em linha.

    {
    "FromEmailAddress": "Mary Major <mary.major@example.com>",
    "DefaultContent": {
        "Template": {
            "TemplateContent": {
                "Subject": "Greetings, {{name}}!",
                "Text": "Dear {{name}},\r\nYour favorite animal is {{favoriteanimal}}.",
                "Html": "<h1>Hello {{name}},</h1><p>Your favorite animal is {{favoriteanimal}}.</p>"
            },
            "TemplateData": "{ \"name\":\"friend\", \"favoriteanimal\":\"unknown\" }"
        }
    },
    "BulkEmailEntries": [
        {
            "Destination": {
                "ToAddresses": [
                    "anaya.iyengar@example.com"
                ]
            },
            "ReplacementEmailContent": {
                "ReplacementTemplate": {
                    "ReplacementTemplateData": "{ \"name\":\"Anaya\", \"favoriteanimal\":\"angelfish\" }"
                }
            }
        },
        {
            "Destination": {
                "ToAddresses": [
                    "liu.jie@example.com"
                ]
            },
            "ReplacementEmailContent": {
                "ReplacementTemplate": {
                    "ReplacementTemplateData": "{ \"name\":\"Liu\", \"favoriteanimal\":\"lion\" }"
                }
            }
        },
        {
            "Destination": {
                "ToAddresses": [
                    "shirley.rodriguez@example.com"
                ]
            },
            "ReplacementEmailContent": {
                "ReplacementTemplate": {
                    "ReplacementTemplateData": "{ \"name\":\"Shirley\", \"favoriteanimal\":\"shark\" }"
                }
            }
        },
        {
            "Destination": {
                "ToAddresses": [
                    "richard.roe@example.com"
                ]
            },
            "ReplacementEmailContent": {
                "ReplacementTemplate": {
                    "ReplacementTemplateData": "{}"
                }
            }
        }
    ],
    "ConfigurationSetName": "ConfigSet"
}

    Esse código contém as seguintes propriedades:

    • FromEmailAddress— O endereço de e-mail do remetente.

    • DefaultContent— Um objeto JSON que contém os TemplateData objetos TemplateContent e.

    • TemplateContent— Um contêiner para os seguintes atributos:

      • Assunto: a linha de assunto do e-mail. Essa propriedade pode conter tags de substituição. Essas tags usam o seguinte formato: {{tagname}}. Quando você envia o e-mail, pode especificar um valor para tagname de cada destino.

      • Html: o corpo HTML do e-mail. Essa propriedade pode conter tags de substituição. O exemplo anterior inclui duas tags: {{name}} e {{favoriteanimal}}.

      • Text: o corpo de texto do e-mail. Os destinatários cujos clientes de e-mail não exibem conteúdo HTML verão esta versão do e-mail. Essa propriedade também pode conter tags de substituição.

    • TemplateData— Contém pares de valores-chave que serão usados se o ReplacementEmailContent objeto contiver um objeto JSON vazio,{}, na propriedade. ReplacementTemplateData

    • BulkEmailEntries— Uma matriz que contém um ou mais Destination objetos.

    • Destino — Um objeto contendo os destinatários de e-mail definidos nas BccAddressespropriedades ToAddressesCcAddresses, e. Elas podem ser usadas em qualquer combinação e podem conter um ou mais endereços de e-mail que receberão o mesmo e-mail.

    • ReplacementTemplateData— Uma string JSON com escape que contém pares de valores-chave. As chaves correspondem às variáveis definidas nas propriedades TemplateContent desse arquivo, por exemplo, {{name}}. Os valores representam o conteúdo que substitui as variáveis no e-mail. (Se a string JSON aqui estiver vazia, indicada por {}, os pares de chave-valor definidos na propriedade TemplateData dentro do objeto DefaultContent serão usados.)

    • ConfigurationSetName— O nome do conjunto de configurações a ser usado ao enviar o e-mail.

      nota

      Recomendamos que você use um conjunto de configurações definido para publicar eventos de falha de processamento no Amazon SNS. Para obter mais informações, consulte (Opcional) Parte 1: Configurar notificações de eventos de falha de renderização.

  2. Altere os valores no código da etapa anterior de acordo com as suas necessidades e salve o arquivo como mybulkemail.json.

  3. Na linha de comando, digite o seguinte comando da API v2 para enviar o e-mail em massa:

    aws sesv2 send-bulk-email --cli-input-json file://mybulkemail.json