Emma API Documentation


These endpoints allow for the invitation and management of users to an HQ subaccount.

POST /#subccount_id/invitation/team

Invite a new user to a subaccount.

Users can only be invited to a single subaccount via the public api. To assign multiple subaccounts to a newly invited user, please do so via the web application.

Additionally, adding further permissions to a newly invited user must also be completed via the web application; this endpoint will assign role type only.

  • invitee_email_address (string) – Required. The email address of the user you'd like to invite.
  • role (string) – Required. The role assigned to the newly created user. The invited user's role must be below your own assigned role. Valid values include: ‘response_only’, ‘author’, ‘editor‘, ‘full’, ‘owner’ (defined as ‘administrator’ in app), and ‘manager’. Role hierarchy is as follows: ‘parent’ > ‘manager’ > ‘owner’ (‘administrator’ in app) > ‘full’ > ‘editor’ > ‘author’ > ‘response_only’
Raises :Http400 if the role provided is invalid.
Raises :Http401 if the requesting user is unable to create a user of that role type.

Sample Response [showhide]
POST /100/invitation/team
  "message": true

Lists the users of an account.

This endpoint allows owners and managers with the ‘manage_users’ permission to list the users for either the parent account, the parent account and all subs, or a particular subaccount.The list returned will include users that have accepted their invitation, and users that have not.

Additionally, there are params to include subaccount users, to filter via ‘account_id’, and to search for a specific user. This endpoint is paginated and will need to be called with pagination params if the response includes more than 500 users.

  • include_sub_users (boolean) – Optional. Calling the endpoint using the ‘parent_account_id’ and this param set to ‘true’ will return the users associated with the parent account along with any users associated with any of the parent's subaccounts as well.
  • searchterm (string) – Optional. Allows searching by the ‘user_id’, ‘user_name_first’, and ‘user_name_last’ values.
  • filter_accounts (comma separated string) – Optional. Allows filtering of the results by returning users who have access to one of the passed accounts.
Returns :A response with a list of users including the accounts they have access to, the permissions they have, their role, and other user related data.
Raises :Http404 if the parent account or requesting user does not exist.
Raises :Http401 if the requesting user does not have access to the account or the ‘manage_users’ permission.

Sample Response [showhide]
GET /100/account/users
    "users": [
            "accounts": [
                    "account_id": 100,
                    "account_name": "Test Parent Account"
            "create_ts": "Jun 21, 2012",
            "email": "emmaHQowner@myemma.com",
            "last_login_attempt": "Jul 22, 2021 02:47 PM",
            "role": "Parent",
            "user_group_list": [
            "user_id": "emmaHQowner@myemma.com",
            "user_name_first": “Test”,
            "user_name_last": “Owner”

Related Topics

Interested in Emma?

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