BrandMail API - addContacts

Syntax

array addContacts(
    string api_key,
    int list_id,
    array contacts,
  [ bool overwrite,
    int remove_unsubscribers ] 
);

Parameters

api_key (string)

The key required to access the API. See Getting Started for more information.

list_id (int)

The ID of the List to add the Contacts to.

contacts (array)

An array containing one or more associative arrays of Contact details. The Contact details are indexed using each of the Field names in the List. See the examples below.

overwrite (bool - optional)

A flag that determines how the method handles duplicates.

Valid values are:

false - Add the Contacts to the List without overwriting any existing Contacts (default).
true - Overwrite the first duplicate instance of a Contact based on the email address Field.

remove_unsubscribers (int - optional)

A flag that determines how the method handles unsubscribed Contacts. Valid values are:

0 - Add all Contacts to the List (default).
1 - Do not add Contacts who have previously unsubscribed from the List.
2 - Do not add Contacts who have previously unsubscribed from any List.

Return Value

Returns an associative array containing the Contact IDs of added and overwritten Contacts. The array is indexed using the corresponding index in the supplied contacts array.

Examples

The following example adds two Contacts to a List:

$list_id = 1234567;

$contacts = array();

$contacts[] = array(

  'First Name' => 'Alice',

  'Email'      => 'alice@example.com'

);

$contacts[] = array(

  'First Name' => 'Bob',

  'Email'      => 'bob@example.com'

);

$api = new Api($url, 'YOURAPIKEY');

$contact_ids = $api->invokeMethod('addContacts', $list_id, $contacts);

// loop over the result

foreach ($contact_ids as $index => $contact_id) {

  print $contacts[$index]['Email'] ." added successfully as Contact ". $contact_id ."\n";

}

{

  "id": 1,

  "method": "addContacts",

  "params": [

      "YOURAPIKEY",

      1234567,

      [

          {

              "First Name": "Alice",

              "Email": "alice@example.com"

          },

          {

              "First Name": "Bob",

              "Email": "bob@example.com"

          }

      ]

  ]

}

{

    "id": 1,

    "result": {

        "0": 15,

        "1": 16

    },

    "error": null

}

Remarks

The "API Upload" Campaign Event is triggered for each Contact that is successfully added or overwritten.

The method does not trigger subscription Autoresponders or send subscription notification messages. See the subscribeContact method if you want to trigger these.

The API does not check the mandatory value of List Fields when adding or editing Contacts.

Error Codes

This method may return the following error codes in addition to the standard error codes:

Code	Error	Description
`303`	Unable to Load List	`list_id` is not a valid List
`330`	Contact Limit Reached	The Contact limit for the Account has been reached. One or more Contacts were not successfully added to the List.
`302`	Undefined Error: No contacts could be added	No Contacts were added to the List. This is usually returned if all Contacts have invalid email addresses or mobile numbers. This error may also be returned if the Contacts array is not an array of one or more associative arrays of Contact details.

addContacts