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:
|
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/ \ |
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/ \ |
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/ \ |
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 |
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 a Simplelists email identifier) |
Query parameters: | None |
Response: | A JSON object containing a single email object |
Example: | curl https://www.simplelists.com/api/2/emails/14334/ -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/ \ |
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/ \ |
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/ \ |
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/ \ |
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/ \ |
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/ \ |
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 |
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:
|
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:
|
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:
|
reject_message | The message that is sent back to the sender if their list email is rejected.
The following variables are available:
|
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:
|
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). |
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/ \ |
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/ \ |
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/ \ |