View a markdown version of this page

Personalização de e-mail avançada - Amazon Simple Email Service
Analisar atributos aninhadosPercorrer listasUsar instruções condicionais básicasCriação de parciais em linha

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á.

Personalização de e-mail avançada

Se estiver usando um modelo armazenado, ou seja, você criou um recurso Template no Amazon SES usando a operação CreateEmailTemplate com a API v2 do SES, poderá aproveitar o sistema Handlebars para criar modelos que incluem recursos avançados, como atributos aninhados, iteração de matriz, instruções condicionais básicas e a criação de parciais em linha. Esta seção fornece exemplos desses recursos.

O Handlebars inclui recursos adicionais além dos documentados nesta seção. Para obter mais informações, consulte Auxiliares integrados em handlebarsjs.com.

nota

O SES não escapa de conteúdo HTML ao renderizar o modelo HTML para uma mensagem. Isso significa que, se você estiver incluindo dados inseridos pelo usuário, como de um formulário de contato, precisará escapá-los no lado do cliente.

Analisar atributos aninhados

O Handlebars inclui suporte para caminhos aninhados, o que torna fácil organizar complexos dados do cliente e, em seguida, consultá-los em seus modelos de e-mail.

Por exemplo, você pode organizar os dados dos destinatários em diversas categorias gerais. Em cada uma dessas categorias, você pode incluir informações detalhadas. O código de exemplo a seguir mostra um exemplo dessa estrutura para um único destinatário:

{
  "meta":{
    "userId":"51806220607"
  },
  "contact":{
    "firstName":"Anaya",
    "lastName":"Iyengar",
    "city":"Bengaluru",
    "country":"India",
    "postalCode":"560052"
  },
  "subscription":[
    {
      "interest":"Sports"
    },
    {
      "interest":"Travel"
    },
    {
      "interest":"Cooking"
    }
  ]
}

Em seus modelos de e-mail, você pode consultar atributos aninhados ao fornecer o nome do atributo pai, seguido por um ponto (.) e pelo nome do atributo para os quais você deseja incluir o valor. Por exemplo, se você usar a estrutura de dados mostrada no exemplo anterior e desejar incluir o nome de cada destinatário no modelo de e-mail, inclua o seguinte texto em seu modelo de e-mail: Hello {{contact.firstName}}!

O Handlebars pode analisar caminhos aninhados em vários níveis de profundidade, o que significa que você tem flexibilidade para escolher como estruturar os dados de seu modelo.

Percorrer listas

A função auxiliar each faz a iteração por meio de itens em uma matriz. O código a seguir é um exemplo de um modelo de e-mail que usa a função auxiliar each para criar uma lista detalhada dos interesses de cada destinatário.

{
  "Template": {
    "TemplateName": "Preferences",
    "SubjectPart": "Subscription Preferences for {{contact.firstName}} {{contact.lastName}}",
    "HtmlPart": "<h1>Your Preferences</h1>
                 <p>You have indicated that you are interested in receiving 
                   information about the following subjects:</p>
                 <ul>
                   {{#each subscription}}
                     <li>{{interest}}</li>
                   {{/each}}
                 </ul>
                 <p>You can change these settings at any time by visiting 
                    the <a href=https://www.example.com/prefererences/i.aspx?id={{meta.userId}}>
                    Preference Center</a>.</p>",
    "TextPart": "Your Preferences\n\nYou have indicated that you are interested in 
                 receiving information about the following subjects:\n
                 {{#each subscription}}
                   - {{interest}}\n
                 {{/each}}
                 \nYou can change these settings at any time by 
                 visiting the Preference Center at 
                 https://www.example.com/prefererences/i.aspx?id={{meta.userId}}"
  }
}
Importante

No código de exemplo anterior, os valores dos atributos HtmlPart e TextPart incluem quebras de linha para facilitar a leitura do exemplo. O arquivo JSON para seu modelo não pode conter quebras de linha dentro desses valores. Se você copiou e colou esse exemplo em seu próprio arquivo JSON, antes de prosseguir, remova as quebras de linha e os espaços extras das seções HtmlPart e TextPart.

Depois de criar o modelo, você pode usar a operação SendEmail ou SendBulkEmail para enviar e-mails para destinatários usando esse modelo. Desde que cada destinatário tenha, pelo menos, um valor no objeto Interests, eles receberão um e-mail que inclua uma lista detalhada de seus interesses. O exemplo a seguir mostra um arquivo JSON que pode ser usado para enviar e-mails para vários destinatários usando o modelo anterior:

{
  "Source":"Sender Name <sender@example.com>",
  "Template":"Preferences",
  "Destinations":[
    {
      "Destination":{
        "ToAddresses":[
          "anaya.iyengar@example.com"
        ]
      },
      "ReplacementTemplateData":"{\"meta\":{\"userId\":\"51806220607\"},\"contact\":{\"firstName\":\"Anaya\",\"lastName\":\"Iyengar\"},\"subscription\":[{\"interest\":\"Sports\"},{\"interest\":\"Travel\"},{\"interest\":\"Cooking\"}]}"
      },
    {
      "Destination":{ 
        "ToAddresses":[
          "shirley.rodriguez@example.com"
        ]
      },
      "ReplacementTemplateData":"{\"meta\":{\"userId\":\"1981624758263\"},\"contact\":{\"firstName\":\"Shirley\",\"lastName\":\"Rodriguez\"},\"subscription\":[{\"interest\":\"Technology\"},{\"interest\":\"Politics\"}]}"
    }
  ],
  "DefaultTemplateData":"{\"meta\":{\"userId\":\"\"},\"contact\":{\"firstName\":\"Friend\",\"lastName\":\"\"},\"subscription\":[]}"
}

Quando você enviar um e-mail para os destinatários listados no exemplo anterior usando a operação SendBulkEmail, eles receberão uma mensagem que se parece com o exemplo mostrado na imagem a seguir:

Notificação de preferências listando esportes, viagens e culinária como interesses selecionados.

Usar instruções condicionais básicas

Esta seção se baseia no exemplo descrito na seção anterior. O exemplo na seção anterior usa o auxiliar each para fazer a iteração por meio de uma lista de interesses. No entanto, os destinatários para os quais nenhum interesse está especificado recebem um e-mail que contém uma lista vazia. Ao usar o auxiliar {{if}}, você poderá formatar o e-mail de forma diferente se um determinado atributo estiver presente nos dados do modelo. O código a seguir usará o auxiliar {{if}} para exibir a lista com marcadores na seção anterior se a matriz Subscription contiver todos os valores. Se a matriz estiver vazia, outro bloco de texto será exibido.

{
  "Template": {
    "TemplateName": "Preferences2",
    "SubjectPart": "Subscription Preferences for {{contact.firstName}} {{contact.lastName}}",
    "HtmlPart": "<h1>Your Preferences</h1>
                 <p>Dear {{contact.firstName}},</p>
                 {{#if subscription}}
                   <p>You have indicated that you are interested in receiving 
                     information about the following subjects:</p>
                     <ul>
                     {{#each subscription}}
                       <li>{{interest}}</li>
                     {{/each}}
                     </ul>
                     <p>You can change these settings at any time by visiting 
                       the <a href=https://www.example.com/prefererences/i.aspx?id={{meta.userId}}>
                       Preference Center</a>.</p>
                 {{else}}
                   <p>Please update your subscription preferences by visiting 
                     the <a href=https://www.example.com/prefererences/i.aspx?id={{meta.userId}}>
                     Preference Center</a>.
                 {{/if}}",
    "TextPart": "Your Preferences\n\nDear {{contact.firstName}},\n\n
                 {{#if subscription}}
                   You have indicated that you are interested in receiving 
                   information about the following subjects:\n
                   {{#each subscription}}
                     - {{interest}}\n
                   {{/each}}
                   \nYou can change these settings at any time by visiting the 
                   Preference Center at https://www.example.com/prefererences/i.aspx?id={{meta.userId}}.
                 {{else}}
                   Please update your subscription preferences by visiting the 
                   Preference Center at https://www.example.com/prefererences/i.aspx?id={{meta.userId}}.
                 {{/if}}"
  }
}
Importante

No código de exemplo anterior, os valores dos atributos HtmlPart e TextPart incluem quebras de linha para facilitar a leitura do exemplo. O arquivo JSON para seu modelo não pode conter quebras de linha dentro desses valores. Se você copiou e colou esse exemplo em seu próprio arquivo JSON, antes de prosseguir, remova as quebras de linha e os espaços extras das seções HtmlPart e TextPart.

O exemplo a seguir mostra um arquivo JSON que pode ser usado para enviar e-mails para vários destinatários usando o modelo anterior:

{
  "Source":"Sender Name <sender@example.com>",
  "Template":"Preferences2",
  "Destinations":[
    {
      "Destination":{
        "ToAddresses":[
          "anaya.iyengar@example.com"
        ]
      },
      "ReplacementTemplateData":"{\"meta\":{\"userId\":\"51806220607\"},\"contact\":{\"firstName\":\"Anaya\",\"lastName\":\"Iyengar\"},\"subscription\":[{\"interest\":\"Sports\"},{\"interest\":\"Cooking\"}]}"
      },
    {
      "Destination":{ 
        "ToAddresses":[
          "shirley.rodriguez@example.com"
        ]
      },
      "ReplacementTemplateData":"{\"meta\":{\"userId\":\"1981624758263\"},\"contact\":{\"firstName\":\"Shirley\",\"lastName\":\"Rodriguez\"}}"
    }
  ],
  "DefaultTemplateData":"{\"meta\":{\"userId\":\"\"},\"contact\":{\"firstName\":\"Friend\",\"lastName\":\"\"},\"subscription\":[]}"
}

Neste exemplo, o destinatário cujos dados do modelo incluíam uma lista de interesses recebe o mesmo e-mail como o exemplo mostrado na seção anterior. No entanto, o destinatário cujos dados do modelo não incluíam interesses recebe um e-mail que se parece com o exemplo mostrado na imagem a seguir:

Mensagem de e-mail com o cabeçalho “Suas preferências” e texto sobre a atualização das preferências de assinatura.

Criação de parciais em linha

Você pode usar parciais em linha para simplificar os modelos que incluem strings repetidas. Por exemplo, é possível criar um parcial em linha que inclua o nome do destinatário e, se estiver disponível, o sobrenome, adicionando o seguinte código no início de seu modelo:

{{#* inline \"fullName\"}}{{firstName}}{{#if lastName}} {{lastName}}{{/if}}{{/inline}}\n
nota

O caractere de nova linha (\n) é necessário para separar o bloco {{inline}} do conteúdo em seu modelo. A nova linha não é renderizada na saída final.

Depois de criar a parcial fullName, você pode incluí-la em qualquer lugar em seu modelo colocando antes do nome da parcial um sinal de maior que (>) seguido por um espaço, como no exemplo a seguir: {{> fullName}}. As parciais em linha não são transferidas entre partes do e-mail. Por exemplo, se você desejar usar a parcial em linha no HTML e na versão de texto do e-mail, defina-a nas seções HtmlPart e TextPart.

Você também pode usar parciais em linha ao fazer a iteração por meio de matrizes. Você pode usar o seguinte código para criar um modelo que use a parcial em linha fullName. Neste exemplo, a parcial em linha se aplica ao nome do destinatário e a uma variedade de outros nomes:

{
  "Template": {
    "TemplateName": "Preferences3",
    "SubjectPart": "{{firstName}}'s Subscription Preferences",
    "HtmlPart": "{{#* inline \"fullName\"}}
                   {{firstName}}{{#if lastName}} {{lastName}}{{/if}}
                 {{/inline~}}\n
                 <h1>Hello {{> fullName}}!</h1>
                 <p>You have listed the following people as your friends:</p>
                 <ul>
                 {{#each friends}}
                   <li>{{> fullName}}</li>
                 {{/each}}</ul>",
    "TextPart": "{{#* inline \"fullName\"}}
                   {{firstName}}{{#if lastName}} {{lastName}}{{/if}}
                 {{/inline~}}\n
                 Hello {{> fullName}}! You have listed the following people 
                 as your friends:\n
                 {{#each friends}}
                   - {{> fullName}}\n
                 {{/each}}"
  }
}
Importante

No código de exemplo anterior, os valores dos atributos HtmlPart e TextPart incluem quebras de linha para facilitar a leitura do exemplo. O arquivo JSON para seu modelo não pode conter quebras de linha dentro desses valores. Se você copiou e colou esse exemplo em seu próprio arquivo JSON, remova as quebras de linha e os espaços extras dessas seções.