addContacts

Adds one or more Contacts to a List.

addContacts

Adds one or more Contacts to a List.

Top ↑

Syntax

object 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 object containing the Contact IDs of added and overwritten Contacts. The object 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.

See Also