:doc:`SESV2 <../../sesv2>` / Client / list_contacts

*************
list_contacts
*************



.. py:method:: SESV2.Client.list_contacts(**kwargs)

  

  Lists the contacts present in a specific contact list.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/sesv2-2019-09-27/ListContacts>`_  


  **Request Syntax**
  ::

    response = client.list_contacts(
        ContactListName='string',
        Filter={
            'FilteredStatus': 'OPT_IN'|'OPT_OUT',
            'TopicFilter': {
                'TopicName': 'string',
                'UseDefaultIfPreferenceUnavailable': True|False
            }
        },
        PageSize=123,
        NextToken='string'
    )
    
  :type ContactListName: string
  :param ContactListName: **[REQUIRED]** 

    The name of the contact list.

    

  
  :type Filter: dict
  :param Filter: 

    A filter that can be applied to a list of contacts.

    

  
    - **FilteredStatus** *(string) --* 

      The status by which you are filtering: ``OPT_IN`` or ``OPT_OUT``.

      

    
    - **TopicFilter** *(dict) --* 

      Used for filtering by a specific topic preference.

      

    
      - **TopicName** *(string) --* 

        The name of a topic on which you wish to apply the filter.

        

      
      - **UseDefaultIfPreferenceUnavailable** *(boolean) --* 

        Notes that the default subscription status should be applied to a contact because the contact has not noted their preference for subscribing to a topic.

        

      
    
  
  :type PageSize: integer
  :param PageSize: 

    The number of contacts that may be returned at once, which is dependent on if there are more or less contacts than the value of the PageSize. Use this parameter to paginate results. If additional contacts exist beyond the specified limit, the ``NextToken`` element is sent in the response. Use the ``NextToken`` value in subsequent requests to retrieve additional contacts.

    

  
  :type NextToken: string
  :param NextToken: 

    A string token indicating that there might be additional contacts available to be listed. Use the token provided in the Response to use in the subsequent call to ListContacts with the same parameters to retrieve the next page of contacts.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'Contacts': [
              {
                  'EmailAddress': 'string',
                  'TopicPreferences': [
                      {
                          'TopicName': 'string',
                          'SubscriptionStatus': 'OPT_IN'|'OPT_OUT'
                      },
                  ],
                  'TopicDefaultPreferences': [
                      {
                          'TopicName': 'string',
                          'SubscriptionStatus': 'OPT_IN'|'OPT_OUT'
                      },
                  ],
                  'UnsubscribeAll': True|False,
                  'LastUpdatedTimestamp': datetime(2015, 1, 1)
              },
          ],
          'NextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **Contacts** *(list) --* 

        The contacts present in a specific contact list.

        
        

        - *(dict) --* 

          A contact is the end-user who is receiving the email.

          
          

          - **EmailAddress** *(string) --* 

            The contact's email address.

            
          

          - **TopicPreferences** *(list) --* 

            The contact's preference for being opted-in to or opted-out of a topic.

            
            

            - *(dict) --* 

              The contact's preference for being opted-in to or opted-out of a topic.

              
              

              - **TopicName** *(string) --* 

                The name of the topic.

                
              

              - **SubscriptionStatus** *(string) --* 

                The contact's subscription status to a topic which is either ``OPT_IN`` or ``OPT_OUT``.

                
          
        
          

          - **TopicDefaultPreferences** *(list) --* 

            The default topic preferences applied to the contact.

            
            

            - *(dict) --* 

              The contact's preference for being opted-in to or opted-out of a topic.

              
              

              - **TopicName** *(string) --* 

                The name of the topic.

                
              

              - **SubscriptionStatus** *(string) --* 

                The contact's subscription status to a topic which is either ``OPT_IN`` or ``OPT_OUT``.

                
          
        
          

          - **UnsubscribeAll** *(boolean) --* 

            A boolean value status noting if the contact is unsubscribed from all contact list topics.

            
          

          - **LastUpdatedTimestamp** *(datetime) --* 

            A timestamp noting the last time the contact's information was updated.

            
      
    
      

      - **NextToken** *(string) --* 

        A string token indicating that there might be additional contacts available to be listed. Copy this token to a subsequent call to ``ListContacts`` with the same parameters to retrieve the next page of contacts.

        
  
  **Exceptions**
  
  *   :py:class:`SESV2.Client.exceptions.BadRequestException`

  
  *   :py:class:`SESV2.Client.exceptions.TooManyRequestsException`

  
  *   :py:class:`SESV2.Client.exceptions.NotFoundException`

  