Lists

The list resource allows contacts to be grouped together. The main interest is to establish distribution lists for sending campaigns, but these lists can also be used to deactivate a set of contacts.

List of properties of the list resource

Property

Description

id

Id of the list of contacts

name

Name of the list of contacts

description

Description of the list of contacts

stats

Statistics of the list of contacts (cf. paragraph for the details)

importErrors

Link to the CSV file containing the list of invalid contacts as well as the reason for which they were not imported.

 

If the list was not created from a file, this parameter is null.

importLines

Number of contacts present in the file that was used to create this list.

 

If the list was not created from a file, this parameter is null.

importInvalid

Number of contacts present in the file that was used to create this list but which were not important because they are invalid.

 

If the list was not created from a file, this parameter is null.

importStatus

Flag making it possible to know whether or not a list is in the process of being imported.

  • "on": The file is being processed

  • "10": percentage processed of the file

  • "ok": The file is fully processed

dateUpdated

Date of the last modification for the contact

dateCreated

Date of creation of the contact

 

By default, only the id, name and description attributes are returned. To access the other attributes, they must be specified in the properties parameter. Recall that the default attributes have an alias via the 'DEFAULT' keyword.

List of statistics returned

Property

Description

subscribers

Number of contacts present in the list

sms

Number of contacts that can be reached for an SMS sending.

 

As such, the following are not counted

  • Contacts that have unsubscribed for this media

  • Contacts that the customer has deliberately unsubscribed

  • Deleted contacts

email

Number of contacts that can be reached for an email sending.

 

As such, the following are not counted

  • Contacts that have unsubscribed for this media

  • Contacts that the customer has deliberately unsubscribed

  • Deleted contacts

  • Hardbounced contacts

voice

Number of contacts that can be reached for a PUSH voice sending.

 

As such, the following are not counted

  • Contacts that have unsubscribed for this media

  • Contacts that the customer has deliberately unsubscribed

  • Deleted contacts

voicemail

Number of contacts that can be reached for Message on answering machine sending.

 

As such, the following are not counted

  • Contacts that have unsubscribed for this media

  • Contacts that the customer has deliberately unsubscribed

  • Deleted contacts

 

Example of the resource in JSON format

{
   "id": "123456789",
   "name": "Ma liste de contacts",
   "dateUpdated": "2013-01-02 14:00:00",
   "dateCreated": "2013-01-01 12:00:00",
   "importErrors": "https://contacts.messengeo.net/rest/list.csv...",
   "importLines": "204586",
   "importInvalid": "50007",
   "importStatus": "ok",
   "stats": {
       "subscribers": "103456",
       "sms": "100003",
       "email": "45689",
       "voice": "564",
       "voicemail": "1025",
   }
}

Reading contact lists

List of available filters

Filter

Description

id

Allows you to select the lists to be retrieved from their id

Example

Retrieving two lists from their ids:

GET /rest/lists HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: contacts.messengeo.net
Content-Type: application/x-www-form-urlencoded
id=12,65

Creating a list of contacts

List of parameters to supply in order to create contacts

Parameters

Description

name

Name of the list of contacts

 

This parameter is required

description

Description of the list of contacts

 

Return

This action returns the list of contact lists created.

{
	"list": [
   	{
       	"id": "7606",
       	"name": "Ma liste de diffusion"
   	}
	],
	"size": 1,
	"total": null
}

Example

POST /rest/lists HTTP/1.1

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: api.messengeo.net
Content-Type: application/x-www-form-urlencoded

name='Ma liste de diffusion'

 

With Curl

curl

-X POST

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d name='Ma liste de diffusion'

https://contacts.messengeo.net/rest/lists

Updating a list of contacts

List of available filters

Filter

Description

id

Allows you to select the lists to be updated according to their id

List of data of the contact list that can be updated

Filter

Description

name

Name of the distribution list

description

Description of the distribution list

This action returns the number of lists concerned by the filter passed as input

{
   count: 10,
}

Example

PUT /rest/lists HTTP/1.1

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: contacts.messengeo.net
Content-Type: application/x-www-form-urlencoded

id=1234&metaData='{"name":"New name of the list","description":"New description of the list"}'

 

With Curl

curl

-X PUT

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d id=1234

-d metaData='{"name":"New name of the list","description":"New description of the list"}'

https://contacts.messengeo.net/rest/lists

Deleting one or more lists of contacts

List of available filters

Filter

Description

id

Allows you to select the lists to be deleted according to their id

 

Return

This method returns the number of contacts concerned by the filter passed as input

{
   count: 10,
}
 

Example

DELETE /rest/lists HTTP/1.1

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: contacts.messengeo.net
Content-Type: application/x-www-form-urlencoded

id=12,78

 

With Curl

curl

-X DELETE

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d id=12,78

https://contacts.messengeo.net/rest/lists

 

Merging lists of contacts (action=merge)

This action allows you to create a list of contacts using two (or more) contact lists.

List of parameters

Parameter

Description

listIds

List of the list ids

name

Name of the list of contacts to be created

 

Note: If one of the contact list ids is not correct, the creating of the new list will not take place. An error is returned indicating the ids with errors.

Return

This action returns the list created following the merger of the other lists:

{
   "size": 1,
   "total": null,
   "list": [
   {
       "id": "2671",
       "name": "Ma liste fusionnée"
   }
   ]
}

Example

POST /rest/lists?action=merge HTTP/1.1

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2…
Host: contacts.messengeo.net
Content-Type: application/x-www-form-urlencoded

listIds=12,78,890&name='Ma liste fusionnée'

 

Avec Curl

curl

-X POST

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d listIds=12,78,890

-d name='Ma liste fusionnée'

https://contacts.messengeo.net/rest/lists?action=merge

 

Importing a contact list from a file (action=import)

This action comprises two steps:

  • Creating a list of contacts.

  • Creating contacts (or updating contacts for those that were already present in the database).

With the return of the REST call, only the list of contacts was created. The contacts are created subsequently asynchronously. It is possible to monitor the unfolding of the import via the import* attributes of the list resource. As such, when importing a large file, the response time corresponds approximately to the upload time of the file on the platform managing the contacts, with the file being processed afterwards.

This action is to be favored (with respect to the create action on a contact) when there is a large number of contacts to create or synchronize.

List of parameters to supply

Parameter

Description

name

Name of the list of contacts to be created

ignoreFirstLine

Indicates if the first line is a column header line (ignoreFirstLine=true) or if it is a contact (ignoreFirstLine=false)

contactFile

Name of the list of contacts

 

Format of the files to be imported

The csv and excel (xls, xlsx) formats are authorized. It is also possible to zip the file in order to save time during the upload. The file cannot exceed a size of 20Mb.

With regards to the format of the column headers, two things are possible:

  • Either the CSV file does not contain any column headers and then the order of the columns of the contacts must comply with the following order: Civility, First name, Last name, Email, Fixed Telephone, Mobile, Fax, Address 1, Address 2, Postal code, City, State, Country, Date of birth, Company, Reference, Field 1, …, Field 15

  • Or the file contains column headers and then, the order of the column is not important as long as the name of the column header is complied with.

Return

This action returns the list created:

{
   "size": 1,
   "total": null,
   "list": [
   {
       "id": "2671",
       "name": "Ma liste importée"
   }
   ]
}
 

Example

curl

-X POST

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d name='Ma liste importée'

-d ignoreFirstLine='true'

-F contactFile=@/path/to/file/liste.csv

https://contacts.messengeo.net/rest/lists?action=import

 

Adding one or more contacts to a list (action=contactadd)

List of available filters

Filter

Description

id

Id of the list to which the contacts are to be added

This parameter is required

 

Specifying the contact or contacts to be added

This data is to be passed in the metaData parameter (cf. examples).

Parameter

Description

contactIds

Ids of the contacts that one wants to add to a contact list

This parameter is required

 

Return

This action returns the number of contacts added in the list

{
   count: 3,
}
 

Example

curl

-X POST

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d id=7606

-d metaData='{"contactIds":"81583724,81583721,81583720" }'

https://contacts.messengeo.net/rest/lists?action=contactadd

 

Removing one or more contacts from a list (action=contactremove)

List of available filters

Filter

Description

id

Id of the list from which the contacts are to be removed

This parameter is required

 

Specifying the contact or contacts to be added

This data is to be passed in the metaData parameter (cf. examples).

Parameter

Description

contactIds

Ids of the contacts that one wants to remove from a contact list

This parameter is required

 

Return

This action returns the number of contacts removed from the list

{
   count: 3,
}
 

Example

curl

-X POST

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"

-d id=7606

-d metaData='{"contactIds":"81583724,81583721,81583720" }'

https://contacts.messengeo.net/rest/lists?action=contactremove