Add several subscribers to a pre-existing mailing list using one operation. You can use the option_update_if_exists element to update existing subscribers. Otherwise, any duplicates will result in an error, but will not impact other additions. This interface can set subscriber details email address, confirmation status and optional custom fields.


XML Request Example:      

<?xml version="1.0" encoding="UTF-8"?>
<xmlrequest>
  <username>username@yourcompany.com</username>
  <usertoken>get-token-from-support</usertoken>
  <requesttype>Lists</requesttype>
  <requestmethod>AddSubscribersToList</requestmethod>
      <details>
      <list>{list_id}</list> <!-- required -->
      <tag>{tag_id or tag_name}</tag>
      <tag>{tag_id or tag_name}</tag>
      <add_to_autoresponders>{add_to_autoresponders_boolean}</add_to_autoresponders>
      <update_if_exists>{update_if_exists_boolean}</update_if_exists>
      <contact> <!-- required -->
            <email>{email_address}</email> <!-- required -->
            <list>{list_id}</list>
            <tag>{tag_id or tag_name}</tag>
            <tag>{tag_id or tag_name}</tag>
            <add_to_autoresponders>{add_to_autoresponders_boolean}</add_to_autoresponders>
            <send_confirmation>{send_confirmation_boolean}</send_confirmation>
            <format>{email_format}</format>
            <ipaddress>{ip_address}</ipaddress>
            <confirmed>{confirmed_boolean}</confirmed>
            <customfield>
                <fieldid>{custom_field_id}</fieldid>
                <value>{custom_field_value}</value>
            </customfield>
            <customfield>
                <fieldid>{custom_field_id}</fieldid>
                <value>{custom_field_value}</value>
            </customfield>
       </contact>
       <contact>
            <email>{email_address}</email> <!-- required -->
            <list>{list_id}</list>
            <tag>{tag_id or tag_name}</tag>
            <tag>{tag_id or tag_name}</tag>
            <add_to_autoresponders>{add_to_autoresponders_boolean}</add_to_autoresponders>
            <send_confirmation>{send_confirmation_boolean}</send_confirmation>
            <format>{email_format}</format>
            <ipaddress>{ip_address}</ipaddress>
            <confirmed>{confirmed_boolean}</confirmed>
            <customfield>
                <fieldid>{custom_field_id}</fieldid>
                <value>{custom_field_value}</value>
            </customfield>
            <customfield>
                <fieldid>{custom_field_id}</fieldid>
                <value>{custom_field_value}</value>
            </customfield>
       </contact>
  </details>
</xmlrequest>

 <xmlrequest> element


Field NameDescription
usernameUsername used to login to Pinpointe
usertokenUnique token assigned to Pinpointe account
requesttypeName of API set to be used
requestmethodFunction being called


<details> element


Field NameDescription
option_update_if_exists (Required)Set as yes to update contact custom fields, instead of generating an error when an email address already appears in list
mailinglistAdd contact to the mailing list with this ID number
tag (optional)

Use one or more elements to assign tags to this subscriber. Values can be the tag's numeric ID or the tag name. Specified tag(s) are added to all subscribers.

add_to_autoresponders (Required)
DEFAULT: false. Set to true to have subscribers added to autoresponders. This will apply to all contacts added via this API call.


<details>

<contact> element - one or more contacts to add to list. Custom fields can be set also.


Field NameDescription
emailaddress (Required)

Address of contact to be added

format

Use html to send user HTML emails or text for plain-text

confirmed (Required)

Use <confirmed>yes</confirmed> to mark user as confirmed. Set user as confirmed if using an opt-in list.

send_confirmation (Required)
Use  <send_confirmation>no</send_confirmation> if <confirmed>yes</confirmed>.  
add_to_autoresponders (Required)
DEFAULT: false. Set to true to have subscribers added to autoresponders. This will apply to the individual contact it is present on, overriding any value set the the <details> level of the XML payload.
tag (optional)

Use one or more elements to assign tags to this subscriber. Values can be the tag's numeric ID or the tag name. These elements will be applied to this contact only.


<details>

<contact> 

<customfields> 

<item> element - add values for a subscriber's custom fields. Use one item element per field.


Field NameDescription
fieldidID of custom field to be added. Built-in fields have pre-identified ID numbers:
  • 2 - First-Name
  • 3 - Last-Name
  • 4 - Phone
  • 8 - City
  • 9 - State
  • 10 - Postal
  • 11 - Country
  • 12 - Industry
  • 13 - Title
  • 14 - Company
For other custom field IDs, hover over the Edit button for that custom field in the web interface
valueValue of this custom field


Successful Response:


<response> element


Field NameDescription
statusWill return SUCCESS if user was successfully added


<response>

<data>

<success> element - contains subscribers added to list


Field NameDescription
quantityContains subscribers added to list
subscribersContains subscribers that could not be added to list. There will be no <subscribers> elements if there are no subscribers added to list.

<emailaddress> — Echo the email address of the subscriber
<subscriberid> — New subscriber ID
<mailinglist> — Mailing list ID that this subscriber was added to
<updated> — This will contain either a “y” or a “n” value indicating if subscribers record were updated instead of creating a new subscribers record. See the option “option_add_if_exists” for xml request value.


<response>

<data>

<failed> element - contains subscribers that could not be added to list


Field NameDescription
quantityContains subscribers added to list
subscribersContains subscribers that could not be added to list. There will be no <subscribers> elements if all subscribers could be added to list.

<emailaddress> — Echo email address that failed
<failed_reason> — Failure reason


Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>SUCCESS</status>
   <data>
      <success>
         <quantity>2</quantity>
         <subscribers>
            <emailaddress>joe@blogs.com</emailaddress>
            <subscriberid>20665255</subscriberid>
            <mailinglist>123</mailinglist>
         </subscribers>
         <subscribers>
            <emailaddress>jane@doe.com</emailaddress>
            <subscriberid>20665256</subscriberid>
            <mailinglist>123</mailinglist>
         </subscribers>
      </success>
      <failed>
         <quantity>1</quantity>
         <subscribers>
            <emailaddress>mick@jagger.com</emailaddress>
            <failed_reason>Subscribers on list</failed_reason>
         </subscribers>
      </failed>
   </data>
</response>