Create contact list

If you have questions regarding this API, please visit our API FAQ page.

Creating a contact list

Make a POST request to https://webapi.inboxroad.com/api/v2/contacts-lists/ with a valid X-API-Key.

curl -X POST 'https://webapi.inboxroad.com/api/v2/contacts-lists/' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Newsletter Subscribers",
    "color": "#7cb7de",
    "description": "Main newsletter contact list"
  }'

Request fields

Field name	Required	Description
label	Yes	Human-readable name shown in dashboards.
color	Yes	Hex color from the allowed palette (see below).
description	No	Description of the list.
unsub_success_redirect_url	No	URL recipients are redirected to after a successful unsubscribe.
unsub_failed_redirect_url	No	URL recipients are redirected to if the unsubscribe link fails.
send_welcome_email	No	Whether to send a welcome email to new contacts. Default false.
welcome_email_subject	No	Subject of the welcome email.
welcome_email_template_id	No	Template id (UUID) used for the welcome email.
welcome_sender_profile_id	No	Sender profile id (UUID) used for the welcome email.

Allowed colors

color must be one of the following palette values:

#cc9ccb  #f0f080  #ecd12d  #dadabc  #7cb7de  #b6d8d5
#065358  #dbe3b4  #c1cceb  #944c6d  #f7819b  #f9c8cb

Note

A new list is created with a default field schema (email, first_name, last_name, status, and so on). Custom fields are managed in the dashboard; the field schema cannot be modified through this endpoint. See Get contact list to inspect a list’s fields.

Example request

{
  "label": "Newsletter Subscribers",
  "color": "#7cb7de",
  "description": "Main newsletter contact list",
  "send_welcome_email": false
}

Response

On success the API returns 200 with the created list, including its field schema in sorted_fields. See Get contact list for the full response shape and a description of the field schema object.

{
  "id": "0fd3d5b4-1c0a-4e91-8a4f-0f17dc6dc5ab",
  "label": "Newsletter Subscribers",
  "color": "#7cb7de",
  "description": "Main newsletter contact list",
  "unsub_success_redirect_url": null,
  "unsub_failed_redirect_url": null,
  "sorted_fields": [
    {
      "id": "b1f3c0a2-1111-4e91-8a4f-0f17dc6dc5ab",
      "label": "Email",
      "column_name": "email",
      "data_type": "EMAIL",
      "required": true,
      "unique": true,
      "default": null,
      "choices": null,
      "max_length": 150,
      "read_only": false,
      "pattern": null
    }
  ],
  "integration_id": null,
  "contacts_import_task_id": null,
  "send_welcome_email": false,
  "welcome_email_subject": null,
  "welcome_email_template_id": null,
  "welcome_sender_profile_id": null
}

Possible response codes

Status code	Description
200	Contact list created successfully.
400	Invalid request data (e.g. missing label/color, or color not in the palette).
401	Unauthorized.