Group Email Manager

login signup

API Protocol Specification

General Format

Request Format

Each API request must be sent in JSON format and consist of 3 main items: entity, action and params. It can also optionally contain an account_id:

  • entity contains the name of the entity upon which you are operating (for example contact).
  • action contains the action that you wish to perform on the entity (for example create).
  • params contains all the data for the request being made.
  • options (optional) contains any options for the request, depending on the type of request
  • account_id (optional) contains the ID of the account. By default the account attached to the user is used. However, for a user with more than one account the account_id must be specified. The account ID can be found by looking at the URL whilst hovering over the "Account" drop-down menu when logged in.

Return Format

The return value is a JSON object. It always contains a key "is_error", which is 0 or 1 accordingly. The other keys depend on the request being made and are detailed below. On an error the key "error_message" is set with the appropriate error message.

Entities

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

Contact

In the case of a Multiple List, the contact entity performs operations on contacts in the central Address Book. For a Single List, it performs operations on List Members. The values for the standard API request are as follows:

Entity: contact
Available actions: get, create, delete, confirm
Params: JSON value. See below for details of required value.
Options:
  • Can optionally contain a key "append_emails". When set to a true value, this ensures that any updates to a contact append rather than replace email addresses.
  • Can optionally contain a key "ignore_duplicates". When set to a true value, this will not do any checking as to whether an email address already exists in another contact. This allows the same email address in multiple contacts, should it be required.
  • For a multiple list, can optionally contain a key with "append_lists". When set to a true value, this ensures that any updates to a contact append list membership if the contact already exists, rather than replacing the list membership.

The value for "params" depends on the action, as detailed in the following table:

Action JSON value for params Return value Example request(s)
get Standard search parameter Object containing key "return", which contains object with contacts. Each item in the returned object has a key of the Simplelists ID and a value containing a contact object. Match surname
{
    "entity": "contact",
    "action":"get",
    "params": {
        "match": "all",
        "conditions": [
            {
                "field": "surname",
                "value": "12%",
                "op":"like"
            }
        ]
    }
}
Match list
{
    "entity": "contact",
    "action":"get",
    "params": {
        "match": "all",
        "conditions": [
            {
                "field": "list",
                "value": {
                    "name" : "test"
                }
            }
        ]
    }
}
create Array of contact objects. Notes:
  • All values in the contact object are optional, apart from "emails"
  • If a Simplelists ID is specified, the contact of that existing ID will be updated instead of a new contact created.
 Object containing key "return", which contains array of contact IDs (either created or updated as applicable) Create multiple contacts 
{
    "entity": "contact",
    "action": "create",
    "params": [
        {
            "surname": "John",
            "firstname": "Smith",
            "emails": [
                {
                    "email": "john@example.com"
                },
                {
                    "email":"jon@example.com"
                }
            ]
        },
        {
            "surname": "Fred",
            "firstname": "Bloggs",
            "emails": [
                {
                    "email": "fred@example.com"
                }
            ]
        }
    ]
}
Add lists to existing contact 
{
    "entity": "contact",
    "action": "create",
    "options": {
        "append_lists": true
    },
    "params": [
        {
            "id": 821259,
            "lists": [
                {
                    "name": "mylist"
                }
            ]
        }
    ]
}
delete An object with one of the four keys described below. Each key should contain an array of the applicable values.
  • cids: Simplelists contact ID values (can be retrieved by using "get").
  • ccids: Custom contact ID values.
  • eids: Simplelists email ID values (can be retrieved by using "get").
  • ceids: Custom email ID values.
 Standard error response. is_error will be 0 on success, and 1 on fail. 
{
    "entity": "contact",
    "action": "delete",
    "params":
    {
        "cids": [
            "3031292"
        ]
    }
}
confirm An object with one of the two keys described below. Each key should contain an array of the applicable values.
  • cids: Simplelists contact ID values (returned on "create", or can be retrieved by using "get").
  • eids: Simplelists email ID values (can be retrieved by using "get").
 Standard error response. is_error will be 0 on success, and 1 on fail. 
{
    "entity": "contact",
    "action": "confirm",
    "params":
    {
        "cids": [
            "3031292"
        ]
    }
}

Membership

The membership entity only applies to a Multiple List account. It is used to remove contacts from lists and update the digest status of specific lists of a contact. When updating the digest status, the list membership must already exist. If it does not exist, an error is thrown. Only the digest status of the specified lists will be updated.

Entity:membership
Available actions:delete, update
Params:JSON value. See below for details of required value.

The value for "params" depends on the action, as detailed in the following table:

Action JSON value for params Return value Example request(s)
delete An object with both the keys described below. Each key should contain an object of the applicable values.
  • contacts: An object with a key of either ccids or cids, and a value as an array containing the respective values.
  • lists: An object with a key of either names or ids, and a value as an array containing the respective values.
 Standard error response. is_error will be 0 on success, and 1 on fail. 
{
    "entity": "membership",
    "action": "delete",
    "params":
    {
        "contacts": {
            "ccids": [
                "3031292"
            ]
        },
        "lists": {
            "names": [
                "listname"
            ]
        }
    }
}
update An object with the keys described below.
  • contacts: An object with a key of either ccids or cids, and a value as an array containing the respective values.
  • lists: An object with a key of either names or ids, and a value as an array containing the respective values.
  • digest: A boolean value (optionally null) specifiying the digest option for this contact and list combination. This value overrides per-list the default digest value for a contact. A value of true means that this contact/list combination will receive digest emails. A value of false means that this contact/list combination will not receive digest emails. A null value uses the contact's default digest setting.
 Standard error response. is_error will be 0 on success, and 1 on fail. 
{
    "entity": "membership",
    "action": "update",
    "params":
    {
        "contacts": {
            "ccids": [
                "3031211"
            ]
        },
        "lists": {
            "names": [
                "listname"
            ]
        },
        "digest": true
    }
}

List

The list entity is used to manage the creation, settings and deletion of lists. Creation and deletion of lists only applies to a Multiple List account.

Entity:list
Available actions:get, create, delete
Params:JSON value. See below for details of required value.

The value for "params" depends on the action, as detailed in the following table:

Action JSON value for params Return value Example request(s)
get Standard search parameter, but field can only be name or id Array of list objects of each list. Match name
{
    "entity": "list",
    "action":"get",
    "params": {
        "match": "all",
        "conditions": [
            {
                "field": "name",
                "value": "mylist%",
                "op": "like"
            }
        ]
    }
}
Match ID
{
    "entity": "list",
    "action":"get",
    "params": {
        "match": "all",
        "conditions": [
            {
                "field": "id",
                "value": 24381
            }
        ]
    }
}
create Array of list objects. Notes:
  • See the list object for a list of valid keys.
  • All values in the list object are optional, apart from one of either "name" or "id"
  • If a Simplelists ID is specified, it must already exist as a list in your account, in which case the list will be updated. If  name  is specified and that already exists, the existing list will be updated, otherwise it will be created.
 Object containing key "return", which contains an array of the IDs of the lists (either created or updated as applicable) 
{
    "entity": "list",
    "action": "create",
    "params": [
        {
            "name": "mylist",
            "maxlength": 1024,
            "subject_prefix": "[My prefix]",
        },
    ]
}
delete An object with one of the two keys described below. Each key should contain an array of the applicable values.
  • ids: Simplelists list ID values (can be retrieved by using "get").
  • names: List names.
 Standard error response. is_error will be 0 on success, and 1 on fail. 
{
    "entity": "list",
    "action": "delete",
    "params":
    {
        "ids": [
            23398
        ]
    }
}

Search parameter

The following details the search parameter, which is used when searching for contacts with the "get" action:

The search parameter is a JSON object, consisting of 2 keys as follows:

match Should contain either the value "all" (to only return values that match all criteria, boolean AND), or the value "any" (to return values that match any criteria - boolean OR).
conditions The conditions to match. An array of objects with the following keys:
  • field: The field name to search. Valid fields depend on which type of object is being searched. See the object section below for a list of valid fields for each type of object.
  • value: The value to search for
  • op: (optional) Set to "like" to be able to use the wildcard % in the value

Objects

This section details the various objects that are sent and received by the API.

Contact object

The contact object contains details of a contact in your account. Not all of the keys apply to all functions.

idInteger containing the Simplelists contact ID
ccidInteger containing custom contact ID
surnameString containing the contact's surname
firstnameString containing the contact's firstname
emailString containing a single email address
emailsAn array of email objects (see below)
addedDate the contact was added
notesString containing any notes
listsAn array of list objects (see below)

Email object

emailString containing the email address
idInteger containing Simplelists email ID
ceidInteger containing custom email ID
digestWhether the email address receives the list digest
confirmedWhether the email address has been confirmed
confsentWhether a confirmation request has been sent
pause_deliveryWhether delivery to the email address is paused

List object

idInteger containing Simplelists internal list ID
nameString containing list name
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
subs_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
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_emailsAn array of email addresses to restrict posting to, in the same format as the web interface (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)
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).
member_countTotal number of members on this list (get requests only).