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>admin</username>
   <usertoken>abc123abc123abc123abc123abc123abc123abc123abc123</usertoken>
   <requesttype>subscribers</requesttype>
   <requestmethod>addsubscriberstolist</requestmethod>
   <details>
      <mailinglist>5</mailinglist>
      <contact>
         <emailaddress>test11@test2.com</emailaddress>
         <format>html</format>
         <confirmed>yes</confirmed>
         <tag>100</tag>
         <tag>Tag Name 1</tag>
         <customfields>
            <item>
               <fieldid>2</fieldid>
               <value>John</value>
            </item>
            <item>
               <fieldid>3</fieldid>
               <value>Smith</value>
            </item>
            <item>
               <fieldid>4</fieldid>
               <value>650-555-1212</value>
            </item>
            <item>
               <fieldid>8</fieldid>
               <value>San_Mateo</value>
            </item>
            <item>
               <fieldid>9</fieldid>
               <value>CA</value>
            </item>
         </customfields>
      </contact>
      <contact>
         <emailaddress>xxx@yyy.com</emailaddress>
         <format>html</format>
         <confirmed>yes</confirmed>
         <customfields>
            <item>
               <fieldid>2</fieldid>
               <value>Bob</value>
            </item>
            <item>
               <fieldid>3</fieldid>
               <value>Smith</value>
            </item>
            <item>
               <fieldid>4</fieldid>
               <value>650-555-1212</value>
            </item>
            <item>
               <fieldid>8</fieldid>
               <value>San_Mateo</value>
            </item>
            <item>
               <fieldid>9</fieldid>
               <value>CA</value>
            </item>
         </customfields>
      </contact>
      <contact>
         <mailinglist>4</mailinglist>
         <emailaddress>zzz@yyy.com</emailaddress>
         <format>html</format>
         <confirmed>yes</confirmed>
         <customfields>
            <item>
               <fieldid>2</fieldid>
               <value>Tom</value>
            </item>
            <item>
               <fieldid>3</fieldid>
               <value><![CDATA[To include strange data escape with CDATA						x & y < 3]]></value>
            </item>
            <item>
               <fieldid>4</fieldid>
               <value>650-555-1212</value>
            </item>
            <item>
               <fieldid>8</fieldid>
               <value>San_Mateo</value>
            </item>
            <item>
               <fieldid>9</fieldid>
               <value>CA</value>
            </item>
         </customfields>
      </contact>
      <tag>25</tag>
      <tag>Tag Name 2</tag>
   </details>
</xmlrequest>

 <xmlrequest> element


Field Name Description
username Username used to login to Pinpointe
usertoken Unique token assigned to Pinpointe account
requesttype Name of API set to be used
requestmethod Function being called


<details> element


Field Name Description
option_update_if_exists (optional) Set as YES to update contact custom fields, instead of generating an error when an email address already appears in list
mailinglist Add 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.


<details>

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


Field Name Description
emailaddress

Address of contact to be added

format

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

confirmed

Use <confirmed>yes</confirmed> to mark user as confirmed. Do not include this XML element to leave user unconfirmed. Set user as confirmed if using an opt-in list.

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 Name Description
fieldid ID 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
value Value of this custom field


Successful Response:


<response> element


Field Name Description
status Will return SUCCESS if user was successfully added

<response>

<data>

<success> element - contains subscribers added to list


Field Name Description
quantity Contains subscribers added to list
subscribers Contains 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 Name Description
quantity Contains subscribers added to list
subscribers Contains 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>