Emma API Documentation

Navigation

Members

In addition to the various CRUD endpoints here related to members, you can also change the status of members, including opting them out.

You’ll notice that there are calls related to individual members, but we also provide quite a few calls to deal with bulk updates of members. Please try to use these whenever possible as opposed to looping through a list of members and calling the individual member calls.

Where this is especially important is when adding new members. To do a bulk import, you’ll POST to the /#account_id/members endpoint. In return, you’ll receive an import ID. You can use this ID to check the status and results of your import. Imports are generally pretty fast, but the time to completion can vary with greater system usage.

GET /#account_id/members

Get a basic listing of all members in an account.

Parameters:
  • deleted (boolean) – Accepts True or 1. Optional flag to include deleted members.
  • deleted_only (boolean) – Accepts True or 1. Optional flag to return only deleted members.
  • deleted_range (string) – Accepts 2 dates (YYYY-MM-DD) delimited by a tilde (~). Example: ``2011-04-01~2011-09-01`` Optional argument to limit results to a date range. If one of the dates is omitted, the default will be either min date or now. If a single date is provided with no tilde, then only members deleted on that date will be included.
  • exclude_fields (boolean) – Accepts True or 1. Optional flag to return only the base attributes of a member
Returns :

A list of members in the given account.

Sample Response [showhide] 
GET /100/members?start=0&end=2

[
  {
    "status": "active",
    "confirmed_opt_in": null,
    "account_id": 100,
    "fields": {
      "first_name": "Emma",
      "last_name": "Smith",
      "favorite_food": "tacos"
    },
    "member_id": 200,
    "sms": {
      "phone_number": "+11234567890",
      "region_code": "US",
      "transactional_status": "a",
      "transactional_status_updated_at": "2023-02-14T21:27:20.723208+00:00",
      "promotional_status": "o",
      "promotional_status_updated_at": "2023-02-14T21:27:20.723208+00:00"
    },
    "last_modified_at": null,
    "member_status_id": "a",
    "plaintext_preferred": false,
    "email_error": null,
    "member_since": "@D:2010-11-12T11:23:45",
    "bounce_count": 0,
    "deleted_at": null,
    "email": "emma@myemma.com"
  },
  {
    "status": "opt-out",
    "confirmed_opt_in": null,
    "account_id": 100,
    "fields": {
      "first_name": "Gladys",
      "last_name": "Jones",
      "favorite_food": "toast"
    },
    "member_id": 201,
    "sms": null,
    "last_modified_at": null,
    "member_status_id": "o",
    "plaintext_preferred": false,
    "email_error": null,
    "member_since": "@D:2011-01-03T15:54:13",
    "bounce_count": 0,
    "deleted_at": null,
    "email": "gladys@myemma.com"
  }
]
Sample Response [showhide] 
GET /100/members?start=2&end=4&deleted=true

[
  {
    "status": "active",
    "confirmed_opt_in": null,
    "account_id": 100,
    "fields": {
      "first_name": "Tony",
      "last_name": "Brown",
      "favorite_food": "pizza"
    },
    "member_id": 202,
    "sms": {
      "phone_number": "+11234567891",
      "region_code": "US",
      "transactional_status": "a",
      "transactional_status_updated_at": "2023-02-14T21:27:20.723208+00:00",
      "promotional_status": "o",
      "promotional_status_updated_at": "2023-02-14T21:27:20.723208+00:00"
    },
    "last_modified_at": null,
    "member_status_id": "a",
    "plaintext_preferred": false,
    "email_error": null,
    "member_since": "@D:2010-11-12T09:12:33",
    "bounce_count": 0,
    "deleted_at": null,
    "email": "tony@myemma.com"
  },
  {
    "status": "active",
    "confirmed_opt_in": null,
    "account_id": 100,
    "fields": {

    },
    "member_id": 203,
    "sms": null,
    "last_modified_at": null,
    "member_status_id": "a",
    "plaintext_preferred": false,
    "email_error": null,
    "member_since": "@D:2011-01-01T00:00:00",
    "bounce_count": 0,
    "deleted_at": "@D:2011-01-02T10:27:43",
    "email": "greg@myemma.com"
  }
]

GET /#account_id/members/#member_id

Get detailed information on a particular member, including all custom fields.

Parameters:
  • deleted (boolean) – Accepts True or 1. Optional flag to include deleted members.
Returns :

A single member if one exists.
Raises :

Http404 if no member is found.

Sample Response [showhide] 
GET /100/members/201

{
  "status": "opt-out",
  "confirmed_opt_in": null,
  "account_id": 100,
  "fields": {
    "first_name": "Gladys",
    "last_name": "Jones",
    "favorite_food": "toast"
  },
  "member_id": 201,
  "sms": {
      "phone_number": "+11234567890",
      "region_code": "US",
      "transactional_status": "a",
      "transactional_status_updated_at": "2023-02-14T21:27:20.723208+00:00",
      "promotional_status": "o",
      "promotional_status_updated_at": "2023-02-14T21:27:20.723208+00:00"
  },
  "last_modified_at": null,
  "member_status_id": "o",
  "plaintext_preferred": false,
  "email_error": null,
  "member_since": "@D:2011-01-03T15:54:13",
  "bounce_count": 0,
  "deleted_at": null,
  "email": "gladys@myemma.com"
}

GET /#account_id/members/email/:email

Get detailed information on a particular member, including all custom fields, by email address instead of ID.

Parameters:
  • deleted (boolean) – Accepts True or 1. Optional flag to include deleted members.
Returns :

A single member if one exists.
Raises :

Http404 if no member is found.

Sample Response [showhide] 
GET /100/members/email/tony@myemma.com

{
  "status": "active",
  "confirmed_opt_in": null,
  "account_id": 100,
  "fields": {
    "first_name": "Tony",
    "last_name": "Brown",
    "favorite_food": "pizza"
  },
  "member_id": 202,
  "sms": null,
  "last_modified_at": null,
  "member_status_id": "a",
  "plaintext_preferred": false,
  "email_error": null,
  "member_since": "@D:2010-11-12T09:12:33",
  "bounce_count": 0,
  "deleted_at": null,
  "email": "tony@myemma.com"
}

GET /#account_id/members/#member_id/optout

If a member has been opted out, returns the details of their optout, specifically date and mailing_id.

Returns :Member opt out date and mailing if member is opted out.
Raises :Http404 if no member is found.

Sample Response [showhide] 
GET /100/members/201/optout

[
  {
    "timestamp": "@D:2014-11-18T22:58:15",
    "mailing_id": 1234567
  }
]

PUT /#account_id/members/email/optout/:email

Update a member’s status to optout keyed on email address instead of an ID.

Returns :True if member status change was successful or member was already opted out.
Raises :Http404 if no member is found.

Sample Response [showhide] 
PUT /100/members/email/optout/tony@myemma.com
{}

true

POST /#account_id/members

Add new members or update existing members in bulk. If you are doing actions for a single member please see the /members/add call below.

Parameters:
  • members (array) – An array of members to update A member is a dictionary of member emails, SMS phone numbers, and field values to import. The only required field is “email”. All other fields are treated as the name of a member field.
  • automate_field_changes (boolean) – Accepts True or False. Optional. When set to True, updates made by this call will trigger field change workflows when appropriate. For more information on field change automation, visit our Resource Center.
  • automate_contact_imports (boolean) – Accepts True or False. Optional. When set to True, updates made by this call will trigger contact import workflows when appropriate.
  • source_filename (string) – An arbitrary string to associate with this import. This should generally be set to the filename that the user uploaded.
  • add_only (boolean) – Optional. Only add new members, ignore existing members.
  • group_ids (array of integers) – Optional. Add imported members to this list of groups.
  • criteria (dictionary) – Optional. Set the sms promotional/transactional statuses for imported members.
Returns :

An import id

Sample Response [showhide] 
POST /100/members
{
  "members": [
    {
      "email": "michelle@myemma.com",
      "sms": {
        "phone_number": "1234567891",
      }
    },
    {
      "email": "nathan@myemma.com",
      "sms": {
        "phone_number": "1234567890",
      }
    }
  ],
  "criteria": {
    "sms": {
      "transactional_status": "a",
      "promotional_status": "a"
    }
  }
}

{
  "import_id": 1024
}

POST /#account_id/members/add

Adds or updates a single audience member. If you are performing actions on bulk members please use the /members call above.

Note: Members who are added to your audience using this API call will
not appear in “recent activity” searches within your account.
Note: If you are using Signup trigger events in Automation, please see this guide for
more information on how this API call affects those trigger events.
Parameters:
  • email (string) – Email address of member to add or update
  • phone_number (string) – A phone number of the member to add or update.
  • fields (dictionary) – Names and values of user-defined fields to update
  • group_ids (array of integers) – Optional. Add imported members to this list of groups.
  • field_triggers (boolean) – Optional. Fires related field change autoresponders when set to true.
  • sms (dictionary) – Optional. sms phone number config for member
    • phone_number (string) – Phone Number
    • promotional_status (string) – Transactional Status
    • transactional_status (string) – Promotional Status
  • subscriber_consent_tracking (boolean) – Optional. Whether or not the user accepts tracking and analysis.
Returns :

The member_id of the new or updated member, whether the member was added or an existing member was updated, and the status of the member. The status will be reported as ‘a’ (active), ‘e’ (error), or ‘o’ (optout).

Sample Response [showhide] 
POST /100/members/add
{
  "fields": {
    "first_name": "Benjamin"
  },
  "email": "benjamin@myemma.com",
  "sms": {
    "phone_number": "1234567890",
    "promotional_status": "o",
    "transactional_status": "a"
  }
}

{
  "status": "a",
  "added": true,
  "member_id": 1024
}

POST /#account_id/members/signup

Takes the necessary actions to signup a member and enlist them in the provided group ids. You can send the same member multiple times and pass in new group ids to signup.

This process triggers the opt-out workflow, and will send a mailing to the member on new group enlistments. If no new group ids are provided for an existing member, the endpoint will respond back with their status and member_id, performing no additional actions.

Note: Members who are added to your audience using this API call will
not appear in “recent activity” searches within your account.
Note: If you are using Signup trigger events in Automation, please see this guide for
more information on how this API call affects those trigger events.
Parameters:
  • email (string) – Email address of the member to sign-up.
  • group_ids (Array of strings (group_ids)) – An array of group ids to associate sign-up with.
  • fields (dictionary) – Optional. Names and values of user-defined fields to update.
  • signup_form_id (integer) – Optional. Indicate that this member used a particular signup form. This is important if you have custom mailings for a particular signup form and so that signup-based triggers will be fired.
  • opt_in_subject (string) – Optional. Override the confirmation message subject with your own copy.
  • opt_in_message (string) – Optional. Override the confirmation message body with your own copy. Must include the following tags: [rsvp_name], [rsvp_email], [opt_in_url], [opt_out_url].
  • field_triggers (boolean) – Optional. Fires related field change autoresponders when set to true.
  • opt_in_confirmation (boolean) – Optional. Sends the default plaintext confirmation email when set to true. NOTE: Confirmation email will be sent by default if this parameter is left out.
  • subscriber_consent_tracking (boolean) – Optional. Whether or not the user accepts tracking and analysis.
Return :

The member_id of the member, and their status. The status will be reported as ‘a’ (active), ‘e’ (error), or ‘o’ (optout).

Sample Response [showhide] 
POST /100/members/signup
{
  "fields": {
    "first_name": "Ryan"
  },
  "group_ids": [
    "1",
    "2"
  ],
  "email": "example@myemma.com",
  "signup_form_id": 1,
  "opt_in_confirmation": true
}

{
  "status": "a",
  "member_id": 1024
}

PUT /#account_id/members/delete

Archive an array of members.

The members will be archived and will be appear in the account's Archived Items section.

Parameters:
  • member_ids (array) – An array of member ids to delete.
Returns :

True if all members are successfully deleted, otherwise False.

Sample Response [showhide] 
PUT /100/members/delete
{
  "member_ids": [
    100,
    101
  ]
}

true

PUT /#account_id/members/status

Change the status for an array of members.

The members will have their member_status_id updated.

Parameters:
  • member_ids (array) – The array of member ids to change.
  • status_to (string) – The new status for the given members. Accepts one of ‘a’ (active), ‘e’ (error), ‘o’ (optout).
Returns :

True if the members are successfully updated, otherwise False.

Sample Response [showhide] 
PUT /100/members/status
{
  "member_ids": [
    200,
    202
  ],
  "status_to": "e"
}

true

PUT /#account_id/members/#member_id

Update a single member’s information.

Update the information for an existing member (even if they are marked as deleted). Note that this method allows the email address to be updated (which cannot be done with a POST, since in that case the email address is used to identify the member).

Parameters:
  • email (string) – A new email address for the member.
  • phone_number (string) – A new phone number for the member.
  • status_to (string) – A new status for the member. Accepts one of ‘a’ (active), ‘e’ (error), ‘o’ (opt-out).
  • fields (array) – An array of fields with associated values for this member.
  • field_triggers (boolean) – Optional. Fires related field change autoresponders when set to true.
  • subscriber_consent_tracking (boolean) – Optional. Whether or not the user accepts tracking and analysis.
Returns :

True if the member was updated successfully
Raises :

Http404 if no member is found.

Sample Response [showhide] 
PUT /100/members/200
{
  "fields": {
    "first_name": "Ella",
    "last_name": "Jones"
  },
  "email": "ella@myemma.com",
  "sms": {
    "phone_number": "1234567891"
  },
  "status_to": "a"
}

true

DELETE /#account_id/members/#member_id

Archive the specified member.

The member will be archived and will appear in the account's Archived Items section.

Returns :True if the member is deleted.
Raises :Http404 if no member is found.

Sample Response [showhide] 
DELETE /100/members/202

true

GET /#account_id/members/#member_id/groups

Get the groups to which a member belongs.

Returns :An array of groups.
Raises :Http404 if no member is found.

Sample Response [showhide] 
GET /100/members/200/groups

[
  {
    "active_count": 1,
    "deleted_at": null,
    "error_count": 0,
    "optout_count": 1,
    "group_type": "g",
    "member_group_id": 150,
    "purged_at": null,
    "account_id": 100,
    "group_name": "Monthly Newsletter"
  },
  {
    "active_count": 2,
    "deleted_at": null,
    "error_count": 0,
    "optout_count": 0,
    "group_type": "g",
    "member_group_id": 151,
    "purged_at": null,
    "account_id": 100,
    "group_name": "Widget Buyers"
  },
  {
    "active_count": 4,
    "deleted_at": null,
    "error_count": 0,
    "optout_count": 0,
    "group_type": "g",
    "member_group_id": 152,
    "purged_at": null,
    "account_id": 100,
    "group_name": "Special Events"
  }
]

PUT /#account_id/members/#member_id/groups

Add a single member to one or more groups.

Parameters:
  • group_ids (array) – Group ids to which to add this member.
Returns :

An array of ids of the affected groups.
Raises :

Http404 if no member is found.

Sample Response [showhide] 
PUT /100/members/200/groups
{
  "group_ids": [
    150,
    151
  ]
}

[
  150,
  151
]

PUT /#account_id/members/#member_id/groups/remove

Remove a single member from one or more groups.

Parameters:
  • group_ids (array) – Group ids from which to remove this member.
Returns :

An array of references to the affected groups.
Raises :

Http404 if no member is found.

Sample Response [showhide] 
PUT /100/members/200/groups/remove
{
  "group_ids": [
    151
  ]
}

[
  151
]

DELETE /#account_id/members

Archive all members.

Parameters:
  • member_status_id (string) – This is ‘a’ (active), ‘o’ (optout), or ‘e’ (error).
Returns :

Returns true.

Sample Response [showhide] 
DELETE /100/members?member_status_id=a

true

DELETE /#account_id/members/#member_id/groups

Remove the specified member from all groups.

Returns :True if the member is removed from all groups.
Raises :Http404 if no member is found.

Sample Response [showhide] 
DELETE /100/members/200/groups

true

PUT /#account_id/members/groups/remove

Remove multiple members from groups.

Parameters:
  • member_ids (array) – Member ids to remove from the given groups.
  • group_ids (array) – Group ids from which to remove the given members.
Returns :

True if the members are deleted, otherwise False.
Raises :

Http404 if any of the members or groups do not exist

Sample Response [showhide] 
PUT /100/members/groups/remove
{
  "group_ids": [
    151
  ],
  "member_ids": [
    202
  ]
}

true

GET /#account_id/members/#member_id/mailings

Get the entire mailing history for a member.

Returns :Message history details for the specified member.

Sample Response [showhide] 
GET /100/members/200/mailings

[
  {
    "delivery_type": "d",
    "clicked": "@D:2011-01-02T11:14:32",
    "opened": "@D:2011-01-02T11:13:51",
    "mailing_id": 200,
    "delivery_ts": "@D:2011-01-02T10:29:36",
    "name": "Sample Mailing",
    "forwarded": null,
    "shared": null,
    "subject": "Sample Mailing for [% member:first_name %] [% member:last_name %]",
    "sent": "@D:2011-01-02T10:27:43",
    "account_id": 100
  }
]

GET /#account_id/members/imports/#import_id/members

Get a list of members affected by this import.

Parameters:
  • all (boolean) – Accepts False or 0. Optional flag to return all members imported by this import.
  • added_only (boolean) – Accepts False or 0. Optional flag to return only members added by this import.
  • added_to_groups (boolean) – Accepts False or 0. Optional flag to return only members added to a group by this import.
Returns :A list of members in the given account and import.

Sample Response [showhide] 
GET /100/members/imports/200/members

[
  {
    "member_id": 200,
    "change_type": "a",
    "member_status_id": "a",
    "email": "emma@myemma.com"
  }
]

GET /#account_id/members/imports/#import_id

Get information and statistics about this import.

Returns :Import details for the given import_id.

Sample Response [showhide] 
GET /100/members/imports/200

{
  "import_id": 200,
  "account_id": 100,
  "import_started": "@D:2010-12-13T23:12:44",
  "import_finished": null,
  "source_name": null,
  "source_filename": null,
  "num_members_added": 0,
  "num_members_updated": 0,
  "num_added_by_group": [],
  "num_duplicates": 0,
  "num_skipped": 0,
  "num_members": 0,
  "num_errors": 0,
  "groups_updated": [],
  "fields_updated": [],
  "status": "o", # for okay (or "e" for error, "q" for queued, "p" for in progress),
  "error_message": null,
  "style": null,
  "automated_field_changes": null
}

GET /#account_id/members/imports

Get information about all imports for this account.

Returns :An array of import details.

Sample Response [showhide] 
GET /100/members/imports

[

]

PUT /#account_id/members/#group_id/copy

Copy all account members of one or more statuses into a group.

Parameters:
  • member_status_id (array of strings) – ‘a’ (active), ‘o’ (optout), and/or ‘e’ (error).
Returns :

True
Raises :

Http404 if the group does not exist.

Sample Response [showhide] 
PUT /100/members/152/copy
{
  "member_status_id": [
    "a",
    "e"
  ]
}

true

PUT /#account_id/members/status/:status_from/to/:status_to
Update the status for a group of members, based on their current
status. Valid statuses id are (‘a’,’e’, ‘f’, ‘o’) active, error, forwarded, optout.
Parameters:
  • group_id – Optional. Limit the update to members of the specified group
Returns :

True
Raises :

Http400 if the specified status is invalid

Sample Response [showhide] 
PUT /100/members/status/e/to/a
{
  "group_id": 1
}

true

POST /#account_id/members/purge

Purge a list of members

This will provide compliance with GDPR right to erasure ('right to be forgotten').

Parameters:
  • member_ids (array of integers) – An array of member ids to purge
Returns :

True
Raises :

Http400 if the specified status is invalid
PUT /#account_id/members/purgeall

Purge all archived members

This will provide compliance with GDPR right to erasure ('right to be forgotten').

Parameters:
  • member_status_id (string) – Optional. This is 'a' (active), 'o' (optout), or 'e' (error).
  • member_group_id (string) – Optional. This is the id of the group
Returns :

True
Raises :

Http400 if the specified status is invalid

Related Topics

Interested in Emma?

Emma's email marketing makes communicating simple and stylish. Get started today.

© Copyright 2003-, Campaign Monitor