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á.
# 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 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html) 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 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html).
Para obter informações sobre ogerenciamento de assinaturas, consulte [Uso de o gerenciamento de assinaturas](sending-email-subscription-management.md).
## 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.
+ Somente 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 SES usando a API [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html).
+ O SES emitirá um evento de falha de entrega para uma mensagem enviada a um contato não registrado na sua lista de contatos. Para obter mais informações, consulte [Uso de o gerenciamento de assinaturas](sending-email-subscription-management.md).
+ 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](https://docs.aws.amazon.com/ses/latest/APIReference-V2/Welcome.html).
### Criar uma lista de contatos
Você pode usar a operação [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html) na API v2 do 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 como instalar e configurar o AWS CLI, consulte o [Guia do AWS Command Line Interface usuário](https://docs.aws.amazon.com/cli/latest/userguide/).
**Para criar uma lista de contatos usando o 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, {{CONTACT-LIST-JSON}} substitua pelo caminho para o arquivo JSON da sua [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContactList.html)solicitação.
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 [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html) na API v2 do 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 como instalar e configurar o AWS CLI, consulte o [Guia do AWS Command Line Interface usuário](https://docs.aws.amazon.com/cli/latest/userguide/).
**Para criar um contato usando o AWS CLI**
+ Na linha de comando, insira o seguinte comando:
```
aws sesv2 create-contact --cli-input-json file://{{CONTACT-JSON}}
```
No comando anterior, {{CONTACT-JSON}} substitua pelo caminho para o arquivo JSON da sua [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateContact.html)solicitação.
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, depois usando a operação [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) na API v2 do 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](sending-email-suppression-list.md#sending-email-suppression-list-manual-add-bulk).
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 {{example1@amazon.com}} e pelos {{example2@amazon.com}} 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 {{Sports}} e {{Cycling}} pelo `topicName` que se aplica ao seu contato. Os aceitáveis `topicPreferences` são {{OPT\_IN}} {{OPT\_OUT}} e.
Os atributos a seguir são suportados ao carregar seus contatos em um objeto do Amazon S3 no formato CSV ou JSON:
[See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/ses/latest/dg/sending-email-list-management.html)
+ Conceda permissão ao SES para ler o objeto do Amazon S3.
Quando aplicada a um bucket do Amazon S3, a seguinte política concede ao SES permissão de leitura desse 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-iam-policies.html) no *Guia do usuário do Amazon Simple Storage Service*.
+ Dê permissão ao SES para usar sua AWS KMS chave.
Se o objeto do Amazon S3 estiver criptografado com uma AWS KMS chave, você precisará dar permissão ao Amazon SES para usar a chave KMS. O SES só pode obter permissão de uma chave gerenciada pelo cliente, não de uma chave padrão do KMS. Você deve conceder ao SES permissão para usar a chave gerenciada pelo cliente, adicionando uma instrução à política de chave.
Cole a seguinte instrução de política na política de chave para permitir que o SES use sua chave gerenciada pelo cliente.
```
{
"Sid": "AllowSESToDecrypt",
"Effect": "Allow",
"Principal": {
"Service":"ses.amazonaws.com"
},
"Action": [
"kms:Decrypt",
],
"Resource": "*"
}
```
+ Use a operação [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_CreateImportJob.html) na API v2 do SES.
**nota**
O exemplo a seguir pressupõe que a AWS CLI já foi instalada. Para obter mais informações sobre como instalar e configurar o AWS CLI, consulte o [Guia do AWS Command Line Interface usuário](https://docs.aws.amazon.com/cli/latest/userguide/).
Na linha de comando, insira o seguinte comando: {{s3bucket}}Substitua pelo nome do bucket do Amazon S3 {{s3object}} e 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.
1. **Liste contatos usando o AWS CLI** — Você pode usar a [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html)operação para recuperar uma lista de todos os seus contatos que se inscreveram em um tópico específico, em conjunto com a [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html)operação, que permite enviar e-mails para eles.
Na linha de comando, insira o seguinte comando:
```
aws sesv2 list-contacts --cli-input-json file://{{LIST-CONTACTS-JSON}}
```
No comando anterior, {{LIST-CONTACTS-JSON}} substitua pelo caminho para o arquivo JSON da sua [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html)solicitação.
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.
1. **Enviar e-mail com `ListManagementOptions` habilitado**: depois de listar os contatos em sua lista usando a operação [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListContacts.html) acima, você pode usar a operação [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_SendEmail.html)para enviar e-mails a cada um de seus contatos utilizando o cabeçalho [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) para especificar a lista de contatos e o nome do tópico.
Para usar `ListManagementOptions` com a operação `SendEmail`, inclua o [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) e o [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) 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 SES emitirá um evento de falha de entrega para uma mensagem enviada a 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.
1. **Indique o local para os links de cancelamento de assinatura**: ao utilizar [https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html](https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_ListManagementOptions.html) você tem a opção de permitir que o 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](sending-email-subscription-management.md).
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}`