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.
welcome_on_embed_form_subscribe	No	Send a welcome email when a contact subscribes via an embed form. Default false.
welcome_on_single_contact_add	No	Send a welcome email when a contact is added individually. Default false.
welcome_email_subject	No	Subject of the welcome email.
welcome_email_template_id	No	Id (UUID) of an email template to use for the welcome email.
welcome_sender_profile_id	No	Id (UUID) of a sender profile to send the welcome email from.
double_opt_in	No	Double opt-in configuration object (see below). Omit to leave double opt-in disabled.

Double opt-in object (double_opt_in)

When double opt-in is enabled, newly added contacts stay pending until they confirm via a confirmation email, then become subscribed.

Field name	Required	Description
enabled	Yes	Whether double opt-in is active for this list.
email_subject	Yes	Subject line of the confirmation email.
sender_profile_id	Yes	Id (UUID) of the sender profile the confirmation email is sent from.
email_template_id	Yes	Id (UUID) of the email template used for the confirmation email.
pending_days	No	Days a contact stays pending before the request expires. One of 1, 3, 7, 14, 30. Default 7.
confirmation_redirect_url	No	URL a contact is redirected to after confirming their subscription.

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",
  "welcome_on_embed_form_subscribe": false,
  "welcome_on_single_contact_add": false,
  "double_opt_in": {
    "enabled": true,
    "email_subject": "Please confirm your subscription",
    "sender_profile_id": "9b8c7d6e-3333-4e91-8a4f-0f17dc6dc5ab",
    "email_template_id": "7d1f0a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "pending_days": 7
  }
}

Response

On success the API returns 200 with the created list, including its field schema in sorted_fields. As with Get contact list, the response embeds the full welcome_email_template, welcome_sender_profile, and double_opt_in objects (or null) rather than their ids. See that page for the full response shape and a description of the field schema and double opt-in objects.

{
  "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,
  "welcome_on_embed_form_subscribe": false,
  "welcome_on_single_contact_add": false,
  "welcome_email_subject": null,
  "welcome_email_template": null,
  "welcome_sender_profile": null,
  "double_opt_in": 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.