Visão geral de gerenciamento de listas Configuração de gerenciamento de listas Demonstração do gerenciamento de listas com exemplos

Uso do gerenciamento de listas

O Amazon SES oferece recursos de gerenciamento de listas, o que significa que os clientes podem gerenciar suas próprias listas de correspondência, conhecidas como listas de contatos. A lista de contatos é uma lista que permite armazenar todos os contatos que se inscreveram em um determinado tópico ou tópicos. Um contato é um usuário final que está recebendo seus e-mails. Um tópico é um grupo de interesse, tema ou rótulo dentro de uma lista. As listas podem ter vários tópicos.

Usando a operação ListContacts na API v2 do Amazon SES, você pode recuperar uma lista de todos os seus contatos que assinaram um tópico específico, para quem você pode enviar e-mails usando a operação SendEmail.

Para obter informações sobre ogerenciamento de assinaturas, consulte Uso de o gerenciamento de assinaturas.

Visão geral de gerenciamento de listas

Você deve considerar os seguintes fatores ao usar o gerenciamento de listas:

Você pode especificar os tópicos da lista ao criá-la.
Apenas uma lista de contatos é permitida por Conta da AWS.
Uma lista pode ter um máximo de 20 tópicos.
Você pode atualizar uma lista de contatos existente, inclusive adicionar novos tópicos à lista, adicionar ou excluir contatos de uma lista e atualizar preferências de contato para uma lista ou tópico.
Você pode atualizar metadados do tópico, como o nome de exibição ou a descrição do tópico.
Você pode obter uma lista dos contatos de uma lista de contatos, contatos que assinaram um tópico, contatos que cancelaram a assinatura de um tópico e contatos que cancelaram todos os tópicos da lista.
Você pode importar suas listas de contatos existentes para o Amazon SES usando a API CreateImportJob.
O Amazon SES devolve um e-mail se ele for enviado para um contato não registrado na sua lista de contatos. Para obter mais informações, consulte Uso de o gerenciamento de assinaturas.
Cada contato pode ter atributos associados, que você pode usar para armazenar informações sobre ele.

Configuração de gerenciamento de listas

Você pode usar as seguintes operações para configurar os recursos de gerenciamento de listas. Para obter a lista completa da lista de contatos e operações de contato, consulte a Referência da API v2 do Amazon SES.

Criar uma lista de contatos

Você pode usar a operação CreateContactList na API v2 do Amazon SES para criar uma lista de contatos. É possível definir essa configuração de forma rápida e fácil usando a AWS CLI. Para obter mais informações sobre a instalação e a configuração da AWS CLI, consulte o Guia do usuário da AWS Command Line Interface.

Para criar uma lista de contatos usando a AWS CLI

Na linha de comando, insira o seguinte comando:


aws sesv2 create-contact-list --cli-input-json file://CONTACT-LIST-JSON

No comando anterior, substitua CONTACT-LIST-JSON pelo caminho para o arquivo JSON de sua solicitação CreateContactList.

Um exemplo de arquivo JSON de entrada CreateContactList para a solicitação é o seguinte:


{
    "ContactListName": "ExampleContactListName",
    "Description": "Creating a contact list example",
    "Topics": [
     {
         "TopicName": "Sports",
         "DisplayName": "Sports Newsletter",
         "Description": "Sign up for our free newsletter to receive updates on all sports.",
         "DefaultSubscriptionStatus": "OPT_OUT"
     },
     {
         "TopicName": "Cycling",
         "DisplayName": "Cycling newsletter",
         "Description": "Never miss a cycling update by subscribing to our newsletter.",
         "DefaultSubscriptionStatus": "OPT_IN"
     },
     {
         "TopicName": "NewProducts",
         "DisplayName": "New products",
         "Description": "Hear about new products by subscribing to this mailing list.",
         "DefaultSubscriptionStatus": "OPT_IN"
     },
     {
         "TopicName": "DailyUpdates",
         "DisplayName": "Daily updates",
         "Description": "Start your day with sport updates, Monday through Friday.",
         "DefaultSubscriptionStatus": "OPT_OUT"
     }
    ]
}

Criar um contato

Você pode usar a operação CreateContact na API v2 do Amazon SES para criar um contato. É possível definir essa configuração de forma rápida e fácil usando a AWS CLI. Para obter mais informações sobre a instalação e a configuração da AWS CLI, consulte o Guia do usuário da AWS Command Line Interface.

Para criar um contato usando a AWS CLI

Na linha de comando, insira o seguinte comando:
```
aws sesv2 create-contact --cli-input-json file://CONTACT-JSON
```
No comando anterior, substitua CONTACT-JSON pelo caminho para o arquivo JSON de sua solicitação CreateContact.

Um exemplo de arquivo JSON de entrada CreateContact para a solicitação é o seguinte:
```
{
    "ContactListName": "ExampleContactListName",
    "EmailAddress": "example@amazon.com",
    "UnsubscribeAll": false,
    "TopicPreferences": [
        {
            "TopicName": "Sports",
            "SubscriptionStatus": "OPT_IN"
        }
    ],
    "AttributesData": "{\"Name\": \"John\", \"Location\": \"Seattle\"}"
}
```
No exemplo acima, um valor UnsubscribeAll de false mostra que o contato não cancelou a assinatura de todos os tópicos. Já um valor de true significaria que o contato cancelou a assinatura de todos os tópicos.

TopicPreferences inclui informações sobre o status de assinatura de tópicos do contato. No exemplo anterior, o contato optou pelo tópico “Esportes” e receberá todos os e-mails do tópico “Esportes”.

O AttributesData é um campo JSON onde você pode colocar qualquer metadado sobre o nosso contato. Ele deve ser um objeto JSON válido.

Importação de contatos em massa para sua lista de contatos

Você pode adicionar manualmente endereços em lote, primeiro carregando seus contatos em um objeto do Amazon S3 e, depois, usando a operação CreateImportJob na API v2 do Amazon SES ou usando o console do SES. Para obter mais informações, consulte Adicionar endereços de e-mail em massa à lista de supressão no nível da conta.

Você deve criar uma lista de contatos antes de importar seus contatos.

nota

Você pode adicionar até 1 milhão de contatos a uma lista de contatos por ImportJob.

Para adicionar contatos em massa à sua lista de contatos, realize as etapas a seguir.

Carregue seus contatos em um objeto do Amazon S3 no formato CSV ou JSON.

Formato CSV

A primeira linha do arquivo carregado para o Amazon S3 deve ser uma linha de cabeçalho.

O objeto topicPreferences precisa ser simplificado para o formato CSV. Cada tópico no topicPreferences terá um campo de cabeçalho separado.

Exemplo de formato CSV para adicionar contatos em lote a uma lista de contatos:



emailAddress,unsubscribeAll,attributesData,topicPreferences.Sports,topicPreferences.Cycling
example1@amazon.com,false,{"Name": "John"},OPT_IN,OPT_OUT
example2@amazon.com,true,,OPT_OUT,OPT_OUT

Formato JSON

Somente arquivos JSON delimitados por nova linha são aceitos. Nesse formato, cada linha é um objeto JSON completo que contém as informações de um contato.

Exemplo de formato JSON para adicionar contatos em lote a uma lista de contatos:


{
     "emailAddress": "example1@amazon.com",
     "unsubscribeAll": false,
     "attributesData": "{\"Name\":\"John\"}",
     "topicPreferences": [
      {
          "topicName": "Sports",
          "subscriptionStatus": "OPT_IN"
      },
      {
          "topicName": "Cycling",
          "subscriptionStatus": "OPT_OUT"
      }
     ]
}
{
     "emailAddress": "example2@amazon.com",
     "unsubscribeAll": true,
     "topicPreferences": [
      {
          "topicName": "Sports",
          "subscriptionStatus": "OPT_OUT"
      },
      {
          "topicName": "Cycling",
          "subscriptionStatus": "OPT_OUT"
      }
     ]
}

Nos exemplos anteriores, substitua exemplo1@amazon.com e exemplo2@amazon.com pelos endereços de e-mail que você deseja adicionar à lista de contatos. Substitua os valores de attributesData pelos valores específicos do contato. Além disso, substitua Esportes e Ciclismo pelo topicName que se aplica ao contato. Os valores aceitáveis para topicPreferences são OPT_IN e OPT_OUT.

Os atributos a seguir são suportados ao carregar seus contatos em um objeto do Amazon S3 no formato CSV ou JSON:

Atributo	Descrição
`emailAddress`	O endereço de e-mail do contato. Este é um campo obrigatório.
`unsubscribeAll`	O status de um valor booleano informando se o contato foi excluído de todos os tópicos da lista de contatos.
`topicPreferences`	As preferências do contato por sua inclusão ou exclusão em tópicos.
`attributesData`	Os dados de atributo anexados a um contato.

Conceda ao Amazon SES permissão para ler o objeto do Amazon S3.

Quando aplicada a um bucket do Amazon S3, a seguinte política concede ao Amazon SES permissão de leitura nesse bucket. Para obter mais informações sobre como anexar políticas aos buckets do Amazon S3, consulte Uso de políticas de bucket e políticas de usuário no Guia do usuário do Amazon Simple Storage Service.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowSESGet",
            "Effect": "Allow",
            "Principal": {
                "Service": "ses.amazonaws.com"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::BUCKET-NAME/OBJECT-NAME",
            "Condition": {
                "StringEquals": {
                    "aws:Referer": "AWSACCOUNTID"
                }
            }
        }
    ]
}

Conceder permissão ao Amazon SES para usar sua chave do AWS KMS.

Se o objeto do Amazon S3 for criptografado com uma chave do AWS KMS, você precisa conceder ao Amazon SES permissão para usar a chave do KMS. O Amazon SES só pode obter permissão para uma chave gerenciada pelo cliente, não para uma chave do KMS padrão. Você deve conceder ao Amazon SES permissão para usar a chave gerenciada pelo cliente, adicionando uma instrução à política ds chaves.

Cole a seguinte instrução de política na política de chaves para permitir que o Amazon SES use sua chave gerenciada pelo cliente.
```
{
   "Sid": "AllowSESToDecrypt", 
   "Effect": "Allow",
   "Principal": {
       "Service":"ses.amazonaws.com"
   },
   "Action": [
       "kms:Decrypt", 
   ],
   "Resource": "*"
}
```
Usar a operação CreateImportJob na API v2 do Amazon SES.

nota

O exemplo a seguir pressupõe que a AWS CLI já foi instalada. Para obter mais informações sobre a instalação e a configuração da AWS CLI, consulte o Guia do usuário da AWS Command Line Interface.

Na linha de comando, insira o seguinte comando: Substitua s3Bucket pelo nome do bucket do Amazon S3 e s3object pelo nome do objeto do Amazon S3.


aws sesv2 create-import-job --import-destination ContactListDestination={ContactListName=ExampleContactListName,ContactListImportAction=PUT} --import-data-source S3Url="s3://s3bucket/s3object",DataFormat=CSV

Demonstração do gerenciamento de listas com exemplos

A demonstração a seguir fornece exemplos de como você pode usar o gerenciamento de listas para listar seus contatos, utilizar ListManagementOptions para especificar uma lista de contatos e um nome de tópico em seu e-mail e como inserir links de cancelamento de assinatura.

Listar contatos usando a AWS CLI: você pode usar a operação ListContacts para recuperar uma lista de todos os seus contatos que assinaram um tópico específico, em conjunto com a operação SendEmail, que permite enviar e-mails a eles.

Na linha de comando, insira o seguinte comando:
```
aws sesv2 list-contacts --cli-input-json file://LIST-CONTACTS-JSON
```
No comando anterior, substitua LIST-CONTACTS-JSON pelo caminho do arquivo JSON de sua solicitação ListContacts.

Um exemplo de arquivo JSON de entrada ListContacts para a solicitação é o seguinte:
```
{
    "ContactListName": "ExampleContactListName",
    "Filter": {
        "FilteredStatus": "OPT_IN",
        "TopicFilter": {
            "TopicName": "Cycling",
            "UseDefaultIfPreferenceUnavailable": true
        }
    },
    "PageSize": 50
}
```
O FilteredStatus mostra o status da assinatura para a qual você deseja filtrar, que é OPT_IN ou OPT_OUT.

O TopicFilter é um filtro opcional que especifica o tópico para o qual você deseja resultados e, no exemplo acima, é “Ciclismo”.

UseDefaultIfPreferenceUnavailable pode ter um valor de true ou false. Se true, a preferência padrão do tópico será usada se o contato não tiver nenhuma preferência explícita para um tópico. Se false, apenas os contatos com uma preferência definida explicitamente serão considerados para filtragem.
Enviar e-mail com ListManagementOptions habilitado: depois de listar os contatos em sua lista usando a operação ListContacts acima, você pode usar a operação SendEmailpara enviar e-mails a cada um de seus contatos utilizando o cabeçalho ListManagementOptions para especificar a lista de contatos e o nome do tópico.

Para usar ListManagementOptions com a operação SendEmail, inclua o contactListName e o topicName aos quais o e-mail pertence (o topicName é opcional):
```
ListManagementOptions:
    String contactListName
    String topicName
                
```
Se você incluir ListManagementOptions na solicitação SendEmail para o endereço de e-mail de um destinatário que não esteja em sua lista de contatos, será criado um contato em sua lista automaticamente.

O Amazon SES devolverá um e-mail se ele for enviado para um contato da sua lista que cancelou a assinatura, o que significa que você não precisa atualizar as solicitações de SendEmail para evitar o envio a contatos que fizeram o cancelamento.
Indique o local para os links de cancelamento de assinatura: ao utilizar ListManagementOptions você tem a opção de permitir que o Amazon SES adicione links de rodapé de cancelamento de assinatura no e-mail usando o espaço reservado {{amazonSESUnsubscribeUrl}} para especificar onde o SES precisa inserir o URL de cancelamento. A substituição de espaço reservado é suportada apenas com os tipos de conteúdo HTML e TEXT. Você pode incluir o espaço reservado duas vezes no máximo. Se for usado mais de duas vezes, apenas as duas primeiras ocorrências são substituídas. Para obter mais informações, consulte Uso de o gerenciamento de assinaturas.

Como alternativa, se estiver usando a interface SMTP para enviar um e-mail, você pode usar o cabeçalho X-SES-LIST-MANAGEMENT-OPTIONS para especificar um nome de lista e de tópico.

Para especificar um nome de lista e tópico ao enviar e-mail usando a interface SMTP, adicione o seguinte cabeçalho de e-mail à sua mensagem:

X-SES-LIST-MANAGEMENT-OPTIONS: {contactListName}; topic={topicName}

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Uso da supressão no nível do conjunto de configurações

Uso de o gerenciamento de assinaturas