Lists Endpoints (v1)

Important! There is a breaking change for all the lists created after July 2, 2020.

Previously you were using numeric list ids when using the endpoints below, but we decided to change list id format in order to improve your lists security.
Since list subscribe/unsubscribe are public API endpoints, anyone could try to guess your list ids and (even though it's very unlikely to guess it) was potentially able to add/remove subscribers on your lists. We didn't want to break the existing API integrations you might have, so we decided to keep subscribe/unsubscribe endpoints public. However, list id is an encrypted token now, rather than an integer.
This way we can be sure that no one will be able add/remove subscribers on your lists without you purposely sharing your token.
In order to obtain list id in a new format you should either visit 'My Lists' section on Sendiio and click on copy list id icon, or retrieve all of your lists with API and get 'encrypted_id' from your lists' data.
Once, again, for lists created prior to the date above you can still use numeric ids, for newer lists that will result in validation error.

Subscribe to a List (programmatically) [public]

Subscribe to email or/and phone list.
Also any additional fields on your request will be picked up and attached to specified email/phone number.

URL
/api/v1/lists/subscribe/json
Method:
POST
Data Params
Required:
email_list_id=[string](required if phone_list_id is not supplied)
phone_list_id=[string](required if email_list_id is not supplied)
email=[string](required if email_list_id is supplied)
phone=[string](required if phone_list_id is supplied)
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "You were successfully subscribed",
    "errors": [],
    "data": []
}

Code: 401
Content:

{
    "error": 1,
    "msg": "Validation errors",
    "errors": [
        "Specified 'email_list_id' is invalid"
    ],
    "data": []
}

Code: 404
Content:

{
    "error": 1,
    "msg": "Error",
    "errors": [
        "Specified 'list_id' does not exist"
    ],
    "data": []
}

Subscribe to a List [public]

Subscribe to email or/and phone list and redirect to specified url (can be used as regular form's action url).
Also any additional fields on your request will be picked up and attached to specified email/phone number.

URL
/api/v1/lists/subscribe
Method:
POST
Data Params
Required:
successfully_subscribed_url=[url]
already_subscribed_url=[url]
email_list_id=[string](required if phone_list_id is not supplied)
phone_list_id=[string](required if email_list_id is not supplied)
email=[string](required if email_list_id is supplied)
phone=[string](required if phone_list_id is supplied)
Response Examples:
Redirect to supplied 'successfully_subscribed_url' or 'already_subscribed_url'

Unsubscribe Email from List [public]

Unsubscribe email from list.

URL
/api/v1/lists/{encrypted_id}/unsubscribe
Method:
POST
Data Params
Required:
email=[string]
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "You were successfully unsubscribed from the list",
    "errors": [],
    "data": []
}

Unsubscribe phone number from list [public]

Unsubscribe phone number from list.

URL
/api/v1/lists/phone/{encrypted_id}/unsubscribe
Method:
POST
Data Params
Required:
phone=[string]
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "You were successfully unsubscribed from the list",
    "errors": [],
    "data": []
}

Get Email List

Get email list details by encrypted id

URL
/api/v1/lists/email/{encrypted_id}
Method:
GET
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "OK",
    "errors": [],
    "data": {
        "list": {
            "id": 16,
            "encrypted_id": "pdiI6Im1LVWhwS1lnUDZnbld4RkZncmp0Z1E9PSIsInZhbHVlIjoiZTU2YVB5QmU4bVZ1VFJ1UUQ2enIwQT09IiwibWFjIjoiMzc4OWM0OTBmYzllMjk5MWI2ODIxYzFkZGIxNDRiYTA1ZDA3MD",
            "name": "test",
            "description": null,
            "notify_for_subscribe": 1,
            "sender_name": "TEST USER",
            "mail_from": null,
            "updated_at": "2019-04-15 14:47:09",
            "created_at": "2019-04-01 13:50:25"
        }
    }
}

Code: 404
Content:

{
    "error": 1,
    "msg": "Error",
    "errors": [
        "Specified list id does not exist"
    ],
    "data": []
}

Get Phone List

Get phone list details by encrypted id

URL
/api/v1/lists/phone/{encrypted_id}
Method:
GET
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "OK",
    "errors": [],
    "data": {
        "list": {
            "id": 1,
            "encrypted_id": "pdiI6Im1LVWhwS1lnUDZnbld4RkZncmp0Z1E9PSIsInZhbHVlIjoiZTU2YVB5QmU4bVZ1VFJ1UUQ2enIwQT09IiwibWFjIjoiMzc4OWM0OTBmYzllMjk5MWI2ODIxYzFkZGIxNDRiYTA1ZDA3MD",
            "name": "test phone",
            "description": null,
            "notify_for_subscribe": 0,
            "created_at": "2019-04-03 13:24:05",
            "updated_at": "2019-04-15 14:47:30"
        }
    }
}

Code: 404
Content:

{
    "error": 1,
    "msg": "Error",
    "errors": [
        "Specified list id does not exist"
    ],
    "data": []
}

Get Email Lists

Get all email lists belonging to the current user

URL
/api/v1/lists/email
Method:
GET
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "OK",
    "errors": [],
    "data": {
        "lists": [
            {
                "id": 16,
                "encrypted_id": "pdiI6Im1LVWhwS1lnUDZnbld4RkZncmp0Z1E9PSIsInZhbHVlIjoiZTU2YVB5QmU4bVZ1VFJ1UUQ2enIwQT09IiwibWFjIjoiMzc4OWM0OTBmYzllMjk5MWI2ODIxYzFkZGIxNDRiYTA1ZDA3MD",
                "name": "test",
                "description": null,
                "notify_for_subscribe": 1,
                "sender_name": "TEST USER",
                "mail_from": null,
                "updated_at": "2019-04-15 14:47:09",
                "created_at": "2019-04-01 13:50:25"
            }
        ]
    }
}

Get Phone Lists

Get all phone lists belonging to the current user

URL
/api/v1/lists/phone
Method:
GET
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "OK",
    "errors": [],
    "data": {
        "lists": [
            {
                "id": 1,
                "encrypted_id": "pdiI6Im1LVWhwS1lnUDZnbld4RkZncmp0Z1E9PSIsInZhbHVlIjoiZTU2YVB5QmU4bVZ1VFJ1UUQ2enIwQT09IiwibWFjIjoiMzc4OWM0OTBmYzllMjk5MWI2ODIxYzFkZGIxNDRiYTA1ZDA3MD",
                "name": "test phone",
                "description": null,
                "notify_for_subscribe": 0,
                "created_at": "2019-04-03 13:24:05",
                "updated_at": "2019-04-15 14:47:30"
            }
        ]
    }
}

Get Email List Fields

Get email list fields by list id

URL
/api/v1/lists/email/fields/{encrypted_id}
Method:
GET
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "OK",
    "errors": [],
    "data": {
        "fields": [
            {
                "id": 1,
                "slug": "first_name",
                "name": "First Name"
            },
            {
                "id": 14,
                "slug": "name",
                "name": "Name"
            }
        ]
    }
}

Code: 404
Content:

{
    "error": 1,
    "msg": "Error",
    "errors": [
        "Specified email list does not exist"
    ],
    "data": []
}

Get Phone List Fields

Get phone list fields by encrypted id

URL
/api/v1/lists/phone/fields/{encrypted_id}
Method:
GET
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "OK",
    "errors": [],
    "data": {
        "fields": [
            {
                "id": 730,
                "slug": "gender",
                "name": "Gender"
            },
            {
                "id": 731,
                "slug": "location",
                "name": "Location"
            }
        ]
    }
}

Code: 404
Content:

{
    "error": 1,
    "msg": "Error",
    "errors": [
        "Specified phone numbers list does not exist"
    ],
    "data": []
}

Get Email List Field Values

Get email list emails along with their field values (only emails that has some field values are returned)

URL
/api/v1/lists/email/fields-values/{encrypted_id}
Method:
GET
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "OK",
    "errors": [],
    "data": [
        {
            "test@gmail.com": {
                "1": {
                    "name": "First Name",
                    "slug": "first_name",
                    "value": "John"
                },
                "14": {
                    "name": "Name",
                    "slug": "name",
                    "value": "John Doe"
                },
                "879": {
                    "name": "Country",
                    "slug": "country",
                    "value": "US"
                }
            },
            "test@live.com": {
                "1": {
                    "name": "First Name",
                    "slug": "first_name",
                    "value": "Jane"
                },
                "14": {
                    "name": "Name",
                    "slug": "name",
                    "value": "Jane Doe"
                }
            }
        }
    ]
}

Code: 404
Content:

{
    "error": 1,
    "msg": "Error",
    "errors": [
        "Specified email list does not exist"
    ],
    "data": []
}

Get Phone List Field Values

Get phone list numbers along with their field values (only phone numbers that has some field values are returned)

URL
/api/v1/lists/phone/fields-values/{encrypted_id}
Method:
GET
Response Examples:
- Code: 200
  Content:

{
    "error": 0,
    "msg": "OK",
    "errors": [],
    "data": [
        {
            "+234234232": {
                "14": {
                    "name": "Name",
                    "slug": "name",
                    "value": "John Doe"
                },
                "879": {
                    "name": "Country",
                    "slug": "country",
                    "value": "US"
                },
                "898": {
                    "name": "City",
                    "slug": "city",
                    "value": "LA"
                }
            },
            "+234234333": {
                "14": {
                    "name": "Name",
                    "slug": "name",
                    "value": "Jane Doe"
                },
                "879": {
                    "name": "Country",
                    "slug": "country",
                    "value": "Canada"
                },
                "898": {
                    "name": "City",
                    "slug": "city",
                    "value": "Vancouver"
                }
            }
        }
    ]
}

Code: 404
Content:

{
    "error": 1,
    "msg": "Error",
    "errors": [
        "Specified phone numbers list does not exist"
    ],
    "data": []
}