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

Value types

Boolean values

Boolean values will be returned as a JSON true or false value.

Boolean values can be set using any true or false value. 0 and an empty string both count as false values. 1 and most other string values with one or more characters count as true values.

Arrays

When a parameter is specified as an array, it will be returned as a JSON list for a read request.

To set a parameter that is specified as an array, multiple body parameters should be passed with the same key for each array value.

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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.simplelists.com/api/2/emails/14334/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:` `curl https://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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	An array of regular expressions to match in email headers to force the emails to be held for approval
taboo_body	An array 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. An email address, or `null` to disable (replies go to the sender)
strip_attachments	Set to a true value to strip attachments from messages
subscriptions	Whether subscriptions are enabled on this list. Set to “open” (enabled), “open+confirm” (enabled with approval by list owner) or “closed” (not enabled). Use a null value to use the account setting.
unsubscriptions	Whether unsubscriptions are enabled on this list. Set to “open” (enabled), “open+confirm” (enabled with approval by list owner) or “closed” (not enabled). Use a null value to use the account setting.
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)
notify_approval	Setting for sending approval notification emails: Null Use account default setting 0 Do not send notification of messages held for approval 1 Notify list manager when any messages are held for approval 2 Delete all messages held for approval 3 Delete messages held for approval if not from list member
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://aoshearman.simplelists.com/api/2/lists/`
Query parameters:	None
Response:	A JSON object containing an array of list objects
Example:	`curl https://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.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://aoshearman.simplelists.com/api/2/lists/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://aoshearman.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://aoshearman.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://aoshearman.simplelists.com/api/2/lists/:name/` (where :name is a Simplelists list name)
Parameters:	None
Response:	A JSON success message
Example:	`curl -X DELETE https://aoshearman.simplelists.com/api/2/lists/mylist/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \`

User

The user object is used for managing users.

General object format

id	Simplelists identifier for the user
username	The username of the user (email address for normal users). Not applicable to API version 2
description	String containing a description of the user (API version 2 keys only)
password	String containing a password for the user (API version 1 only)
can_write	Boolean as to whether the user has write permissions (API version 1 only)
surname	Surname of the user
firstname	First name of the user
cidr	CIDR IP address restriction for the user (API version 2 only)
custom_image	Boolean as to whether the account's custom image banner is shown for this user
mfa_type	Multi-factor authentication type (“otp”, “sms” or undefined)
api	The version of the API that this user is for, or 0 if this is not an API user
authentication_type	Authentication type, using the name of the authentication provider (SSO-enabled accounts only)
notifications	An array listing the email notifications that the user receives. Changing this setting will replace all existing values. Available array values are: list_manager Emails sent to list manager email addresses account Account management related emails subscription Member subscription and unsubscription notification emails bounce_removal Notifications and warnings of member removal due to undeliverable emails bounce Notifications of undeliverable emails approval Notifications of emails requiring approval
permissions	An array listing the permissions of the user. Changing this setting will replace all exisitng values. Available array values are: superadmin Super-adminstrator (add and edit other users) account Multi-account administrator (grouped accounts only) list User can manage lists (create, delete, copy) general_settings User can manage general account settings list_settings User can manage list settings approval User can moderate emails held for approval contact User can manage all contacts (including membership) alias User can manage aliases membership User can manage list members audit User can view audit logs billing User can manage account billing limit_lists User is limited to specific lists only limit_metadata User is limited to specific custom metadata only
limit_metadata	An array of custom metadata that this user is limited to, if limit_metadata is true for the user's permissions. The metadatum's identifier is used (if defined), otherwise the full name is used.
limit_lists	An array of lists that this user is limited to, if limit_lists is true for the user's permissions

Retrieving all users

Use a GET request to retrieve all users in an account.

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

Retrieving a single user

Use a GET request to retrieve a single user object by id or username.

Method:	GET
URI:	`https://aoshearman.simplelists.com/api/2/users/:id/` (where :id is the ID or username of a user)
Query parameters:	None
Response:	A JSON object containing a single user object
Examples:	`curl https://aoshearman.simplelists.com/api/2/users/34521/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:` `curl https://aoshearman.simplelists.com/api/2/users/bob%40example.com/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:`

Updating a user object

Use a PUT request to update a single user object.

Method:	PUT
URI:	`https://aoshearman.simplelists.com/api/2/users/:id/` (where :id is a Simplelists user ID)
Body parameters:	Add all or any of a user object's properties to the body of the request to update them
Response:	A JSON object containing the updated user object
Example:	`curl https://aoshearman.simplelists.com/api/2/users/2341/ \ -X PUT \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d firstname=Bob \ -d surname=Smith \ -d permissions=list \ -d permissions=approval`

Creating a new user object

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

Method:	POST
URI:	`https://aoshearman.simplelists.com/api/2/users/`
Body parameters:	Use the parameters of a user object in the body of the request. At a minimum a username must be provided.
Response:	A JSON object containing the created user object
Example:	`curl https://aoshearman.simplelists.com/api/2/users/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d username=bob@example.com \ -d permissions=approval \`

Deleting a user object

Use a DELETE request to delete a user.

Method:	DELETE
URI:	`https://aoshearman.simplelists.com/api/2/users/:id/` (where :id is a Simplelists user ID)
Parameters:	None
Response:	A JSON success message
Example:	`curl -X DELETE https://aoshearman.simplelists.com/api/2/users/1345/ \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \`

Retrieving an API key

Use a PUT request to retrieve an API key, using special body parameters.

Method:	PUT
URI:	`https://aoshearman.simplelists.com/api/2/users/:id/` (where :id is a Simplelists user ID)
Body parameters:	Specify the parameter `get_key` with no value and optionally `expiry_months` with value of 1, 3, 6 or 12
Response:	A JSON object containing the key and expiry date if applicable
Example:	`curl https://aoshearman.simplelists.com/api/2/users/2341/ \ -X PUT \ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: \ -d get_key= \ -d expiry_months=6`