Contacts: Lists

Add To Lists

Put up to 500 existing contacts in one or more lists, subscribed.

POSThttps://g.sendcorex.com/v1/contactscommand: add_to_lists
i

Needs the contact:update scope on your API key.

i

Every list must exist. If one does not, the whole command fails with NOT_FOUND before any contact is touched. Contacts that do not exist fail on their own item.

Arguments

  • emailsstring[]optional

    Up to 500 emails. Case and surrounding spaces are ignored, and repeated emails count once.

  • emailstringoptional

    A single email. Use this or emails.

  • list_idsstring[]required

    The lists to join.

    e.g. ["customers", "newsletter"]

  • list_idstringoptional

    A single list. Use this or list_ids.

  • return_contactsbooleanoptional

    Add the whole contact after the change to each item.

Quick start

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/contacts',
  {
    commands: [
      {
        command: "add_to_lists",
        args: {
          emails: [
            "ana@acme.com"
          ],
          list_ids: [
            "customers",
            "newsletter"
          ]
        }
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);

const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);

Response

{
  "type": "SUCCESS",
  "results": [
    {
      "command": "add_to_lists",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 14,
      "data": {
        "items": [
          {
            "id": "ana@acme.com",
            "ok": true,
            "data": {
              "changed": true
            }
          }
        ],
        "ok_count": 1,
        "failed_count": 0
      }
    }
  ]
}

Response fields

  • items[].id

    The email you sent, as you sent it.

  • items[].ok

    true when this email worked. When false, the item has code and message.

  • items[].data.changed

    false when the contact was already in all of these lists.

  • items[].data.contact

    The whole contact after the change. Only with return_contacts: true.

  • ok_count / failed_count

    How many emails worked and how many failed.

New contacts

Add To Lists only works on contacts that exist. To create and add in one step, use Upsert Contacts with list_id.

Errors

HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.

  • 401INVALID_API_KEY

    The API key does not exist, was revoked or was disabled in the dashboard.

  • 429RATE_LIMITED

    More than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.

  • CMDMISSING_SCOPE

    The API key does not have the scope this command needs. The other commands in the request still run.

  • CMDINVALID_ARGS

    A required argument is missing or invalid: email, field value, enum option, where key, list id…

  • CMDNOT_FOUND

    The contact, list, field or segment does not exist.

  • CMDINTERNAL

    Server error. The detail is only written to the server log.