Members¶

class audience.api.controllers.members.MemberController(app, request, response)¶

Contains web service functions for operating with member data.

list_members(account_id)¶

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.
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, 
		"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, 
		"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, 
		"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, 
		"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_member_detail(account_id, member_id)¶

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, 
	  "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_member_detail_by_email(account_id, email)¶

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, 
	  "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_member_optout_detail(account_id, member_id)¶

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

	[]
	

import_member_list(account_id)¶

POST /#account_id/members

Add new members or update existing members.

Parameters:	members (array) – An array of members to update

A member is a dictionary of member emails and field values to import. The only required field is “email”. All other fields are treated as the name of a member field.

Parameters:	source_filename (string) – An arbitrary string to associate with this import.

This should generally be set to the filename that the user uploaded.

Parameters:	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.
Returns:	An import id

Sample Response [showhide]

	POST /100/members
	{
	  "members": [
		{
		  "email": "michelle@myemma.com"
		}, 
		{
		  "email": "nathan@myemma.com"
		}
	  ]
	}

	{
	  "import_id": 1024
	}
	

import_single_member(account_id)¶

POST /#account_id/members/add

Adds or updates an audience member

Parameters:

email (string) – Email address of member to add or update fields (dictionary) – Names and values of user-defined fields to update group_ids (integer) – Optional. Add imported members to this list of groups. signup_form_id – Optional. Indicate that this member used a particular signup form. This is important if you have custom confirmation messages for a particular signup form and so that signup-based triggers will be fired.

Returns:

The member_id of the new or updated member, and whether the member was added or an existing member was updated

Sample Response [showhide]

	POST /100/members/add
	{
	  "fields": {
		"first_name": "Benjamin"
	  }, 
	  "email": "benjamin@myemma.com"
	}

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

delete_members(account_id)¶

PUT /#account_id/members/delete

Delete an array of members.

The members will be marked as deleted and cannot be retrieved.

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
	

update_members_status(account_id, safeties_off=False)¶

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’, ‘e’, ‘o’ (active, error, 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
	

update_member(account_id, member_id, private=False)¶

PUT /#account_id/members/#member_id

Update a single member’s information.

Update the information for an existing member. 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. status_to (string) – A new status for the member. Accepts one of ‘a’, ‘e’, ‘o’ (active, error, opt-out). fields (array) – An array of fields with associated values for this member.
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", 
	  "status_to": "a"
	}

	true
	

delete_member(account_id, member_id)¶

DELETE /#account_id/members/#member_id

Delete the specified member.

The member, along with any associated response and history information, will be completely removed from the database.

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

Sample Response [showhide]

	DELETE /100/members/202

	true
	

list_member_groups(account_id, member_id)¶

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, 
		"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, 
		"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, 
		"account_id": 100, 
		"group_name": "Special Events"
	  }
	]
	

add_member_to_groups(account_id, member_id)¶

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
	]
	

remove_member_from_groups(account_id, member_id)¶

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
	]
	

remove_all_members(account_id)¶

DELETE /#account_id/members

Delete all members.

Parameters:	member_status_id (string) – This is ‘a’ctive, ‘o’ptout, or ‘e’error.
Returns:	Returns true.

Sample Response [showhide]

	DELETE /100/members?member_status_id=a

	true
	

remove_member_from_all_groups(account_id, member_id)¶

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
	

remove_members_from_groups(account_id)¶

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_member_mailing_history(account_id, member_id)¶

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_import_stats_members(account_id, import_id)¶

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

Get a list of members affected 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_import_stats(account_id, import_id)¶

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, 
	  "status": null, 
	  "style": null, 
	  "import_started": "@D:2010-12-13T23:12:44", 
	  "account_id": 100, 
	  "error_message": null, 
	  "num_members_updated": 0, 
	  "source_filename": null, 
	  "fields_updated": [], 
	  "num_members_added": 0, 
	  "import_finished": null, 
	  "groups_updated": [], 
	  "num_skipped": 0, 
	  "num_duplicates": 0
	}
	

get_all_import_stats(account_id)¶

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

	[]
	

mark_import_as_deleted(account_id)¶

DELETE /#account_id/members/imports/delete

Update an import record to be marked as ‘deleted’.

Returns:	True if the import is marked as deleted.
Raises :	Http404 if the import record does not exist

copy_to_group(account_id, group_id)¶

PUT /#account_id/members/#group_id/copy

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

Parameters:	member_status_id (array) – ‘a’ctive, ‘o’ptout, and/or ‘e’rror.
Returns:	True
Raises :	Http404 if the group does not exist.

Sample Response [showhide]

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

	true
	

bulk_change_member_status(account_id, status_from, status_to)¶

PUT /#account_id/members/status/:status_from/to/:status_to

Update the status for a group of members, based on their current

status

Parameters:	group_id – Optional. Limit the update to members of the specified group
Returns:	True
Raises :	Http404 if the specified status is invalid

Sample Response [showhide]

	PUT /100/members/status/e/to/a
	{
	  "group_id": 1
	}

	true