Email list hosting service & mailing list manager

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

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
  • 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
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
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.

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.

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 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/ \
-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

idSimplelists identifier for the list
nameString containing list name
descriptionString containing the list description
createdThe date the list was created (read-only)
contactsThe Simplelists identifiers of the contacts that are members of this list
maxlengthMaximum message size in KB
truncateLength in bytes to truncate messages to, or null to disable
subject_prefixSubject prefix of the list
moderatorAlternative moderator of the list
memberview Whether list members can view other members (noemail, withemail, all-noemail, all-withemail or empty string to disable)
message_footerPlain text message footer of the list
message_footer_htmlHTML message footer of the list
message_fronterPlain text message fronter of the list
message_fronter_htmlHTML message fronter of the list
taboo_headersA list of regular expressions to match in email headers to force the emails to be held for approval
reply_toThe reply-to email address of the list (null for the list default, empty string to disable)
strip_attachmentsSet to a true value to strip attachments from messages
hold_automatedSet to a true value to hold automated emails for approval
restrict_post_allowed_emailsAn array of email addresses to allow to post to the list (moderate must also be set appropriately)
restrict_post_banned_emailsAn array of email addresses to ban posting to the list (moderate must also be set appropriately)
restrict_post_listsAn array of list names to restrict posting to (moderate must also be set appropriately)
moderateThe 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_messageAn optional message to send to new list members
welcome_message_subjectThe email subject of the optional message to send to new list members
hold_messageThe 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_subjectThe 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_messageThe 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_subjectThe 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_enabledSet to a true value to enable archives
archive_spammodeSet to a true value to hide email addresses in the archives
archive_protectedSet to a true value to disable open access of the archives
archive_passwordIf 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_memberviewSet 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/membership/: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/4236/ -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/membership/ \
-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: \