API Protocol Specification (version 2)

General Format

Request Format

Each API request consists of a relevant URI to signify the object or objects being retrieved or updated, and optionally body parameters where an update is being made. Requests are made with a variety of HTTP request methods depending on the operation being performed:

GET used to retrieve objects
PUT used to update objects
POST used to create new objects
DELETE used to delete objects

URL format

Please note that all URLs end with a trailing slash. This is for consistency across all endpoints. Whilst redirects will normally be used when a URL is used that does not end in a slash, this will not necessarily work for POST or PUT requests.

Return Format

The return value is always a JSON object. For a GET, PUT or POST request it will contain the updated or retrieved objects. For a DELETE request it will simply be {success:1} if the request succeeded.

Error handling

If for any reason a request fails then a JSON object in the following format will be returned:

{"is_error":true,"message":"Authentication failed"}

In this case is_error will always be true and the relevant error message will be stipulated in the message field.

In addition, a suitable HTTP response code will be used:

400 Bad Request Invalid request
403 Forbidden The API key does not have permission for the request
404 Not Found API request does not exist
409 Conflict Attempt to create new contact when custom contact ID already exists
429 Too Many Requests API rate limit exceeded
500 Server Error Internal server error at Simplelists

Rate limits

A rate limit is in place for the API. The measurement of use is based on the number of returned or affected objects. Query or update of a single object counts as a single use. Retrieval of lists of objects counts as the number of objects returned. The rate limit of objects is 3 times the maximum size of an account's address book per hour. The counter resets on the hour every hour. If these rate limits are troublesome for your use then please let us know.

Objects

This section details each of the objects available, along with the possible actions and the parameters that should be sent.

Contact

The contact object is used for managing contacts in an account's address book (or list members in the case of a Single List account).

General object format

id	Simplelists identifier for the contact
ccid	Custom identifier for the contact. If enabled for the account, these replace the Simplelists identifier in API calls
firstname	The first name of the contact
surname	The surname of the contact
created	The date the contact was created (read-only)
notes	Any notes attached to the contact
emails	An array of email objects
lists	An array of membership objects
<custom field>	Custom metadata fields are referred to by their identifier (if defined) or otherwise their name

Retrieving a single contact

Use a GET request to retrieve a single contact using a Simplelists identifier.

Method:	GET
URI:	`https://www.simplelists.com/api/2/contacts/:id/` (where :id is a Simplelists contact identifier)
Query parameters:	None
Response:	A JSON object containing a single contact object
Example:	`curl https://www.simplelists.com/api/2/contacts/23934/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:`

Retrieving multiple contacts

Use a GET request to retrieve several contacts, optionally using search parameters.

Method:	GET
URI:	`https://www.simplelists.com/api/2/contacts/`
Query parameters:	Optionally use the following URL parameters: page to request the page number of the results limit to specify the number of contacts in the response (default 100, maximum 1000) search to specify a search to be undertaken across all contact properties id to search a specific Simplelists ID
Response:	A JSON list containing contact objects
Example:	`curl https://www.simplelists.com/api/2/contacts/?page=2&search=smith&limit=10 -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:`

Updating a contact

Use a PUT request to update a single contact. If an account is ccid enabled, then a PUT request to an ID that does not exist will create that resource first.

Method:	PUT
URI:	`https://www.simplelists.com/api/2/contacts/:id/` (where :id is a Simplelists contact identifier)
Body parameters:	Add all or any of a contact object's properties to the body of the request to update them
Response:	A JSON object containing the updated contact
Example:	`curl https://www.simplelists.com/api/2/contacts/2352134/ \ -X PUT \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d surname=Jones`

Creating a new contact

Use a POST request to create a single contact. If an account is ccid enabled, then a POST request will create that contact if the custom ID does not exist, otherwise a 409 error will be thrown.

Method:	POST
URI:	`https://www.simplelists.com/api/2/contacts/`
Body parameters:	Use the parameters of a contact object in the body of the request. At a minimum an email address must be provided.
Response:	A JSON object containing the created contact
Example:	`curl https://www.simplelists.com/api/2/contacts/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d firstname=John \ -d surname=Smith \ -d lists=mylist \ -d lists=otherlist \ -d emails=john@example.com`

Deleting a contact

Use a DELETE request to delete a single contact.

Method:	DELETE
URI:	`https://www.simplelists.com/api/2/contacts/:id/` (where :id is a Simplelists contact identifier)
Parameters:	None
Response:	A JSON success message
Example:	`curl -X DELETE https://www.simplelists.com/api/2/contacts/2352134/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \`

Email

The email object is used for managing email addresses within a contact.

General object format

id	Simplelists identifier for the email address
contact	The identifier of the contact that this email object belongs to
email	The email address of the object
digest	Whether this email address receives daily digest format (1 or 0)
paused	Whether delivery is paused for this email address (1 or 0)
confirmed	Whether this email address has been confirmed (read-only)
ceid	A custom identifier for the object

Retrieving a single email address

Use a GET request to retrieve a single email address using a Simplelists identifier.

Method:	GET
URI:	`https://www.simplelists.com/api/2/emails/:id/` (where :id is an email address or a Simplelists email identifier)
Query parameters:	None
Response:	A JSON object containing a single email object
Examples:	`curl https://www.simplelists.com/api/2/emails/14334/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:` `curl https://www.simplelists.com/api/2/emails/john%40example.com/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:`

Updating an email address

Use a PUT request to update a single email object.

Method:	PUT
URI:	`https://www.simplelists.com/api/2/emails/:id/` (where :id is a Simplelists email identifier)
Body parameters:	Add all or any of an email object's properties to the body of the request to update them
Response:	A JSON object containing the updated email object
Example:	`curl https://www.simplelists.com/api/2/emails/4562345/ \ -X PUT \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d digest=1`

Creating a new email object

Use a POST request to create a new email address for a contact.

Method:	POST
URI:	`https://www.simplelists.com/api/2/emails/`
Body parameters:	Use the parameters of an email object in the body of the request. At a minimum an email address and contact must be provided.
Response:	A JSON object containing the created email object
Example:	`curl https://www.simplelists.com/api/2/emails/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d email=alex@example.com \ -d contact=345234 \ -d digest=1 \`

Deleting an email address

Use a DELETE request to delete a single email object. This will also delete the contact if the contact only contains this email address.

Method:	DELETE
URI:	`https://www.simplelists.com/api/2/emails/:id/` (where :id is a Simplelists email identifier)
Parameters:	None
Response:	A JSON success message
Example:	`curl -X DELETE https://www.simplelists.com/api/2/emails/5623214/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \`

Membership

The email object is used for managing a contact's list membership.

General object format

id	Simplelists identifier for the membership
contact	The identifier of the contact that this membership relates to
list	The list name that this membership relates to
digest	The digest setting for this membership, if overriding that of the email address. Use an undefined value to retain the default of the email address, or 1 or 0 to override receiving or not receiving the daily digest option respectively.

Retrieving a single membership object

Use a GET request to retrieve a single membership object using a Simplelists identifier.

Method:	GET
URI:	`https://www.simplelists.com/api/2/membership/:id/` (where :id is a Simplelists membership identifier)
Query parameters:	None
Response:	A JSON object containing a single membership object
Example:	`curl https://www.simplelists.com/api/2/membership/4362346/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:`

Updating a membership object

Use a PUT request to update a single membership object.

Method:	PUT
URI:	`https://www.simplelists.com/api/2/membership/:id/` (where :id is a Simplelists membership identifier)
Body parameters:	Add all or any of a membership object's properties to the body of the request to update them
Response:	A JSON object containing the updated membership object
Example:	`curl https://www.simplelists.com/api/2/membership/3422543/ \ -X PUT \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d digest=1`

Creating a new membership object

Use a POST request to add a contact to a list.

Method:	POST
URI:	`https://www.simplelists.com/api/2/membership/`
Body parameters:	Use the parameters of a membership object in the body of the request. At a minimum a contact ID and list name must be provided.
Response:	A JSON object containing the created membership object
Example:	`curl https://www.simplelists.com/api/2/membership/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d contact=3426494 \ -d list=mylist \`

Deleting a membership object

Use a DELETE request to remove a contact from a list.

Method:	DELETE
URI:	`https://www.simplelists.com/api/2/membership/:id/` (where :id is a Simplelists membership identifier)
Parameters:	None
Response:	A JSON success message
Example:	`curl -X DELETE https://www.simplelists.com/api/2/membership/436214/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \`

List

The email object is used for managing lists.

General object format

id	Simplelists identifier for the list
name	String containing list name
description	String containing the list description
notes	A general-use string field to store miscellaneous data
created	The date the list was created (read-only)
contacts	The Simplelists identifiers of the contacts that are members of this list
maxlength	Maximum message size in KB
truncate	Length in bytes to truncate messages to, or null to disable
subject_prefix	Subject prefix of the list
moderator	Alternative moderator of the list
memberview	Whether list members can view other members (`noemail`, `withemail`, `all-noemail`, `all-withemail` or empty string to disable)
message_footer	Plain text message footer of the list
message_footer_html	HTML message footer of the list
message_fronter	Plain text message fronter of the list
message_fronter_html	HTML message fronter of the list
taboo_headers	A list of regular expressions to match in email headers to force the emails to be held for approval
taboo_body	A list of regular expressions to match in the email body to force the emails to be held for approval
reply_to	The reply-to email address of the list (`null` for the list default, empty string to disable)
strip_attachments	Set to a true value to strip attachments from messages
hold_automated	Set to a true value to hold automated emails for approval
restrict_post_allowed_emails	An array of email addresses to allow to post to the list (`moderate` must also be set appropriately)
restrict_post_banned_emails	An array of email addresses to ban posting to the list (`moderate` must also be set appropriately)
restrict_post_lists	An array of list names to restrict posting to (`moderate` must also be set appropriately)
moderate	The posting restrictions. Any of the following values can be ANDed together: 0 (no moderation) 1 (all messages held) 2 (choose specific senders as per `4` and `8`) 4 (allow members of lists configured in `restrict_post_lists` to send) 8 (allow emails configured in `restrict_post_emails` to send)
welcome_message	An optional message to send to new list members
welcome_message_subject	The email subject of the optional message to send to new list members
hold_message	The message that is sent back to the sender if their list email is held for approval. The following variables are available: $SUBJECT (the subject of the sender's email) $LISTNAME (the email address of the list)
hold_subject	The subject of the message that is sent back to the sender if their list email is held for approval. The following variables are available: $LISTNAME (the email address of the list)
reject_message	The message that is sent back to the sender if their list email is rejected. The following variables are available: $SUBJECT (the subject of the sender's email) $LISTNAME (the email address of the list)
reject_subject	The subject of the message that is sent back to the sender if their list email is rejected. The following variables are available: $LISTNAME (the email address of the list)
archive_enabled	Set to a true value to enable archives
archive_spammode	Set to a true value to hide email addresses in the archives
archive_protected	Set to a true value to disable open access of the archives
archive_password	If set, this is the password to access the archives (`archive_protected` must also be enabled). If set to a blank value, password access to list archives is disabled. This parameter can only be set, not retrieved.
archive_memberview	Set to a true value to allow list members to access protected archives (`archive_protected` must also be enabled to protect the archives).
archive_index_noshow	Set to a true value to hide the archives from the public archives list.

Retrieving all lists

Use a GET request to retrieve all lists of an account.

Method:	GET
URI:	`https://www.simplelists.com/api/2/lists/`
Query parameters:	None
Response:	A JSON object containing an array of list objects
Example:	`curl https://www.simplelists.com/api/2/lists/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:`

Retrieving a single list

Use a GET request to retrieve a single list object by name.

Method:	GET
URI:	`https://www.simplelists.com/api/2/lists/:name/` (where :name is the name of the list)
Query parameters:	None
Response:	A JSON object containing a single list object
Example:	`curl https://www.simplelists.com/api/2/lists/mylist/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:`

Updating a list object

Use a PUT request to update a single list object.

Method:	PUT
URI:	`https://www.simplelists.com/api/2/lists/:name/` (where :name is a Simplelists list name)
Body parameters:	Add all or any of a list object's properties to the body of the request to update them
Response:	A JSON object containing the updated list object
Example:	`curl https://www.simplelists.com/api/2/list/mylist/ \ -X PUT \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d strip_attachments=1`

Creating a new list object

Use a POST request to add a new list to an account.

Method:	POST
URI:	`https://www.simplelists.com/api/2/lists/`
Body parameters:	Use the parameters of a list object in the body of the request. At a minimum a list name must be provided.
Response:	A JSON object containing the created list object
Example:	`curl https://www.simplelists.com/api/2/lists/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d name=mylist \ -d moderate=6 \`

Deleting a list object

Use a DELETE request to delete a list.

Method:	DELETE
URI:	`https://www.simplelists.com/api/2/list/:name/` (where :name is a Simplelists list name)
Parameters:	None
Response:	A JSON success message
Example:	`curl -X DELETE https://www.simplelists.com/api/2/lists/mylist/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \`