Utilizzo della gestione degli elenchi - Amazon Simple Email Service
Panoramica della gestione degli elenchiConfigurazione della gestione degli elenchiProcedura dettagliata per la gestione degli elenchi con esempi

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Utilizzo della gestione degli elenchi

Amazon SES offre funzionalità di gestione degli elenchi, il che significa che i clienti possono gestire le proprie mailing list, note come liste di contatti. Un elenco di contatti è un elenco che consente di archiviare tutti i contatti che sono iscritti a uno o più argomenti specifici. Un contatto è un utente finale che riceve le tue email. Un argomento è un gruppo di interesse, un tema o un'etichetta all'interno di un elenco. Gli elenchi possono avere più argomenti.

Utilizzando il comando ListContacts nell'API Amazon SES v2, è possibile recuperare un elenco di tutti i contatti che si sono iscritti a un determinato argomento, ai quali è possibile inviare e-mail utilizzando il comando SendEmail.

Per informazioni sulla gestione delle sottoscrizioni, consulta Utilizzo della gestione delle sottoscrizioni.

Panoramica della gestione degli elenchi

Quando si utilizza la gestione elenchi, è necessario considerare i seguenti fattori:

  • È possibile specificare gli argomenti dell'elenco durante la creazione dell'elenco.

  • È consentito un solo elenco di contatti per Account AWS.

  • Un elenco può avere un massimo di 20 argomenti.

  • È possibile aggiornare un elenco contatti esistente, inclusi l'aggiunta di nuovi argomenti all'elenco, l'aggiunta o l'eliminazione di contatti da un elenco e l'aggiornamento delle preferenze dei contatti per un elenco o un argomento.

  • È possibile aggiornare i metadati dell'argomento, ad esempio il nome visualizzato o la descrizione dell'argomento.

  • È possibile ottenere un elenco di contatti in un elenco contatti, contatti sottoscritti a un argomento, contatti disiscritti da un argomento e contatti disiscritti da tutti gli argomenti dell'elenco.

  • Puoi importare gli elenchi di contatti esistenti su Amazon SES utilizzando l'API CreateImportJob.

  • Amazon SES non recapiterà un'e-mail se viene inviata a un contatto non iscritto nell'elenco dei contatti. Per ulteriori informazioni, consulta Utilizzo della gestione delle sottoscrizioni.

  • Ogni contatto può avere attributi associati che è possibile utilizzare per memorizzare informazioni su quel contatto.

Configurazione della gestione degli elenchi

È possibile utilizzare le seguenti operazioni di seguenti per configurare le funzionalità di gestione degli elenchi. Per l'elenco completo dell'elenco dei contatti e delle operazioni dei contatti, consulta il Documento di riferimento all'API Amazon SES v2.

Creazione di un elenco di contatti

Puoi utilizzare il comando CreateContactList nell'API Amazon SES v2 per creare un elenco di contatti. Puoi configurare rapidamente e facilmente questa impostazione utilizzando l'AWS CLI. Per ulteriori informazioni sull'installazione e la configurazione dell'AWS CLI, consulta la Guida per l'utente di AWS Command Line Interface.

Creazione di un elenco di contatti mediante l'AWS CLI

  • Nella riga di comando, inserisci il comando seguente:

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

    Nel precedente comando, sostituire CONTACT-LIST-JSON con il percorso del file JSON per la richiesta CreateContactList.

    Un esempio di file JSON di input CreateContactList per la richiesta è il seguente:

    {
    "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"
     }
    ]
}

Creazione di un contatto

Puoi utilizzare il comando CreateContact nell'API Amazon SES v2 per creare un contatto. Puoi configurare rapidamente e facilmente questa impostazione utilizzando l'AWS CLI. Per ulteriori informazioni sull'installazione e la configurazione dell'AWS CLI, consulta la Guida per l'utente di AWS Command Line Interface.

Creazione di un contatto mediante l'AWS CLI

  • Nella riga di comando, inserisci il comando seguente:

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

    Nel precedente comando, sostituire CONTACT-JSON con il percorso del file JSON per la richiesta CreateContact.

    Un esempio di file JSON di input CreateContact per la richiesta è il seguente:

    {
    "ContactListName": "ExampleContactListName",
    "EmailAddress": "example@amazon.com",
    "UnsubscribeAll": false,
    "TopicPreferences": [
        {
            "TopicName": "Sports",
            "SubscriptionStatus": "OPT_IN"
        }
    ],
    "AttributesData": "{\"Name\": \"John\", \"Location\": \"Seattle\"}"
}

    Nell'esempio precedente, un valore UnsubscribeAll di false indica che il contatto non ha annullato la sottoscrizione a tutti gli argomenti, laddove un valore di true significherebbe che il contatto ha annullato la sottoscrizione a tutti gli argomenti.

    TopicPreferences include informazioni sullo stato della sottoscrizione del contatto agli argomenti. Nell'esempio precedente, il contatto ha scelto l'argomento "Sports" e riceverà tutti i messaggi di posta elettronica relativi all'argomento "Sports".

    AttributesData è un campo JSON in cui è possibile inserire qualsiasi tipo di metadati sul nostro contatto. Deve essere un oggetto JSON valido.

Importazione in blocco dei contatti nell'elenco di contatti

Puoi aggiungere manualmente gli indirizzi in blocco caricando prima i contatti in un oggetto Simple Storage Service (Amazon S3), seguito dall'operazione CreateImportJob nell'API Amazon SES v2 o utilizzando la console SES. Per ulteriori informazioni, consulta Aggiunta di indirizzi e-mail in blocco all'elenco di eliminazione a livello di account.

È necessario creare un elenco di contatti prima di importare i contatti.

Nota

È possibile aggiungere fino a 1 milione di contatti a un elenco di contatti per ImportJob.

Per aggiungere contatti in blocco all'elenco di contatti, procedere come segue.

  • Carica i tuoi contatti in un oggetto Amazon S3 in formato CSV o JSON.

    Formato CSV

    La prima riga del file che viene caricato su Amazon S3 dovrebbe essere una riga di intestazione.

    L'oggetto topicPreferences deve essere appiattito per il formato CSV. Ogni argomento in topicPreferences avrà un campo di intestazione separato.

    Esempio di formato CSV per l'aggiunta di contatti in blocco a un elenco di contatti:

    
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

    Sono supportati solo i file JSON delimitati da nuova riga. In questo formato, ogni riga è un oggetto JSON completo che contiene le informazioni di un contatto.

    Esempio di formato JSON per l'aggiunta di contatti in blocco a un elenco di contatti:

    {
     "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"
      }
     ]
}

    Negli esempi precedenti, sostituire example1@amazon.com ed example2@amazon.com con gli indirizzi e-mail che si desidera aggiungere all'elenco di contatti. Sostituire i valori attributesData con i valori specifici del contatto. Inoltre, sostituire Sports e Cycling con topicName che si applica al contatto. Le topicPreferences accettabili sono OPT_IN e OPT_OUT.

    I seguenti attributi sono supportati durante il caricamento dei contatti in un oggetto Simple Storage Service (Amazon S3) in formato CSV o JSON:

    Attributo Descrizione
    emailAddress L'indirizzo email del contatto. Questo è un campo obbligatorio.
    unsubscribeAll Uno stato di valore booleano che indica se il contatto è disiscritto da tutti gli argomenti dell'elenco di contatti.
    topicPreferences Preferenze del contatto per l'accettazione o l'esclusione degli argomenti.
    attributesData Dati degli attributi allegati a un contatto.

  • Consente ad Amazon SES l'autorizzazione a leggere l'oggetto Amazon S3.

    Se applicata a un bucket Amazon S3, la seguente policy concede ad Amazon SES l'autorizzazione a leggere tale bucket. Per maggiori informazioni sulle policy dei bucket per Amazon S3, consulta Utilizzo delle policy dei bucket e dell'utente nella Guida per l'utente di 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"
                }
            }
        }
    ]
}

  • Concede ad Amazon SES l'autorizzazione a utilizzare la chiave AWS KMS.

    Se l'oggetto Amazon S3 è crittografato con una chiave AWS KMS, devi concedere ad Amazon SES l'autorizzazione necessaria per utilizzare la chiave KMS. Amazon SES può ottenere l'autorizzazione solo da una chiave gestita dal cliente, non da una chiave KMS predefinita. Devi concedere ad Amazon SES l'autorizzazione a utilizzare la chiave gestita dal cliente aggiungendo un'istruzione alla policy della chiave.

    Incolla la seguente istruzione nella policy della chiave per consentire ad Amazon SES di utilizzare la tua chiave gestita dal cliente.

    {
   "Sid": "AllowSESToDecrypt", 
   "Effect": "Allow",
   "Principal": {
       "Service":"ses.amazonaws.com"
   },
   "Action": [
       "kms:Decrypt", 
   ],
   "Resource": "*"
}

  • Utilizzare il comando CreateImportJob nell'API Amazon SES v2.

Nota

L'esempio seguente presuppone che sia già installata l'AWS CLI. Per ulteriori informazioni sull'installazione e la configurazione dell'AWS CLI, consulta la Guida per l'utente di AWS Command Line Interface.

Nella riga di comando, immetti il comando seguente: Sostituire s3bucket con il nome del bucket Amazon S3 e s3object con il nome dell'oggetto Amazon S3.

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

Procedura dettagliata per la gestione degli elenchi con esempi

La seguente procedura dettagliata fornisce esempi di come utilizzare la gestione degli elenchi per elencare i contatti, utilizzareListManagementOptions per specificare un elenco di contatti e il nome dell'argomento nell'e-mail e come inserire i collegamenti di annullamento della sottoscrizione.

  1. Elencare i contatti mediante l'AWS CLI: utilizzando il comando ListContacts è possibile recuperare un elenco di tutti i contatti che si sono iscritti a un determinato argomento, insieme al comando SendEmail che consente di inviare loro e-mail.

    Nella riga di comando, inserisci il comando seguente:

    aws sesv2 list-contacts --cli-input-json file://LIST-CONTACTS-JSON

    Nel precedente comando, sostituire LIST-CONTACTS-JSON con il percorso al file JSON per la richiesta ListContacts.

    Un esempio di file JSON di input ListContacts per la richiesta è il seguente:

    {
    "ContactListName": "ExampleContactListName",
    "Filter": {
        "FilteredStatus": "OPT_IN",
        "TopicFilter": {
            "TopicName": "Cycling",
            "UseDefaultIfPreferenceUnavailable": true
        }
    },
    "PageSize": 50
}

    FilteredStatus mostra lo stato della sottoscrizione per il quale si desidera filtrare, ovvero OPT_IN o OPT_OUT.

    TopicFilter è un filtro facoltativo che specifica l'argomento per cui si desidera ottenere risultati e, nell'esempio precedente, è "Cycling".

    UseDefaultIfPreferenceUnavailable può avere un valore di true o false. Se true, verrà utilizzata la preferenza predefinita dell'argomento se il contatto non dispone di alcuna preferenza esplicita per un argomento. Se false, solo i contatti con una preferenza impostata esplicitamente vengono considerati per il filtraggio.

  2. Invia posta con ListManagementOptions abilitato: dopo aver elencato i contatti nell'elenco utilizzando il precedente comando ListContacts, è possibile utilizzare il comando SendEmail per inviare e-mail a ciascun contatto utilizzando l'intestazione ListManagementOptions per specificare l'elenco dei contatti e il nome dell'argomento.

    Per utilizzare ListManagementOptions con il comando SendEmail, includere contactListName e topicName a cui appartiene l'e-mail (topicName è facoltativo):

    
ListManagementOptions:
    String contactListName
    String topicName

    Se includi ListManagementOptions nella richiesta SendEmail a un indirizzo e-mail del destinatario che non è presente nell'elenco dei contatti, verrà creato automaticamente un contatto nell'elenco.

    Amazon SES non recapiterà un'e-mail se viene inviata a un contatto non iscritto nell'elenco dei contatti, il che significa che non dovrai aggiornare le richieste SendEmail per evitare l'invio a contatti che hanno annullato la sottoscrizione.

  3. Indicare la posizione per i collegamenti di annullamento della sottoscrizione: quando si utilizza ListManagementOptions hai la possibilità di abilitare Amazon SES di aggiungere collegamenti a piè di pagina di annullamento della sottoscrizione nella tua e-mail utilizzando il placeholder {{amazonSESUnsubscribeUrl}} per specificare dove SES deve inserire l'URL di annullamento della sottoscrizione. La sostituzione dei placeholder è supportata solo per i tipi di contenuto HTML e TEXT. È possibile includere il placeholder al massimo due volte. Se usato più di due volte, vengono sostituite solo le prime due occorrenze. Per ulteriori informazioni, consulta Utilizzo della gestione delle sottoscrizioni.

    In alternativa, puoi utilizzare l'intestazione X-SES-LIST-MANAGEMENT-OPTIONS per specificare un elenco e un nome di argomento durante l'invio di e-mail utilizzando l'interfaccia SMTP.

    Per specificare il nome di un elenco e di un argomento durante l'invio di e-mail utilizzando l'interfaccia SMTP, aggiungere la seguente intestazione di posta elettronica al messaggio:

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