Emma API Documentation


These endpoints allow you to manage subaccounts under an HQ parent account.

POST /#parent_account_id/enterprise/subaccount

Creates a subaccount under the given parent account

  • account_name (string) – Required. The name of the subaccount.
  • account_rsvp_email (string) – Optional (recommended.) This is the ‘sender email’ that the subaccount’s mailings will be shown as sent from.
  • account_rsvp_name (string) – Optional (recommended.) This is the ‘sender name’ displayed on the subaccount’s mailings.
  • account_rsvp_address_1 (string) – Optional (recommended.) First line of the address for the subaccount.
  • account_rsvp_address_2 (string) – Optional. Second line of the address for the subaccount.
  • account_rsvp_country (string) – Optional (recommended.) Country for the subaccount (must match 2 letter iso code or capitalized country name.) Including this additionally requires city & state parameters (or city & province if outside the US.)
  • account_rsvp_city (string) – Optional (recommended.) City for the subaccount.
  • account_rsvp_province (string) – Optional. Province for the subaccount (only for accounts outside the US.)
  • account_rsvp_state (string) – Optional (recommended.) State for the subaccount (full capitalized state name or capitalized 2 letter abbreviation.)
  • account_rsvp_zip_code (string) – Optional (recommended.) Zipcode or postal code for the subaccount.
  • account_status (string) – Optional. This sets the status of the subaccount; must be ‘active’ or ‘trial’. HQ parent accounts in ‘trial’ status that attempt to create ‘active’ subaccounts will have those subaccounts created as ‘trial’.
  • account_timezone (string) – Optional (recommended.) Time zone information for the subaccount formatted in the tz database name standard.
  • country_abbrev (boolean string) – Optional. ‘true’ or ‘false’ (used for personalization.)
  • send_response_summary (boolean) – Optional. This setting sends relevant subaccount users a response summary email 24 hours after mailing has been sent.
  • show_code_your_own (boolean) – Optional, This setting allows subaccount to use HTML to create mailings instead of the drag & drop editor.
  • show_blank_template (boolean) – Optional. This setting makes a blank template available for customization.
Returns :

A response with the newly created subaccount's ‘account_id’, the ‘account_name’ of the newly created subaccount, and the ‘parent_account_id’ of the HQ parent.

Sample Response [showhide]
POST /100/enterprise/subaccount
  "account_name": "Test Account Name",
  "account_id": 101,
  "parent_account_id": 100,

DELETE /#parent_account_id/enterprise/subaccount/#subaccount_id

Retires a subaccount.

Be advised that using this endpoint will remove the subaccount from the HQ account, and all of the data associated with the subaccount will be purged completely from our system and will be unretrievable after 30 days. If you accidentally retire a subaccount, you will need to reach out to our Support team for assistance, as the subaccount cannot be re-instituted through the API.

Returns :A response with the subaccount's ‘account_name’ and the ‘status’ of ‘retired’.
Raises :Http404 if the subaccount does not exist.

Sample Response [showhide]
DELETE /100/enterprise/subaccount/101
  "account_name": "Test Account Name",
  "status": "retired",


Gets a list of subaccounts.

This endpoint provides a list of subaccounts that the requesting user has access to. Calling this endpoint with no query parameters will return subaccounts in ‘active’, ‘trial’, ‘pending_retirement’, and ‘retired’ status. This endpoint is paginated, so if you have more than 500 subaccounts, you'll need to make multiple requests using the pagination params.

  • status (comma separated string) – Optional. Allows filtering based on subaccount status. Valid statuses are: ‘active’, ‘trial’, ‘pending_retirement’, and ‘retired’.
  • searchterm (string) – Optional. Allows searching by the ‘account_name’ value.
Returns :A response with a list of subaccounts including their ‘account_name’, ‘account_id’, and their ‘account_status’.
Raises :Http404 if the parent account does not exist.

Sample Response [showhide]
GET /100/enterprise/subaccounts?start=0&end=2
    "subaccounts": [
            "account_id": 101,
            "account_name": "Test Account Name",
            "account_status": "active"
            "account_id": 102,
            "account_name": "Test Account Name 2",
            "account_status": "retired"


Assign subaccounts to a user.

This endpoint allows owners, and managers with the ‘manage_users’ permission, to assign subaccounts to a specific ‘user_id’. The list of subaccounts provided in the call will overwrite the current list of subaccounts the user has access to, so you’ll need to ensure you’ve included every subaccount ID applicable to the user you are editing.

  • accounts (list of integers) – Required. The list of subaccounts to assign to the user.
Raises :Http400 if a non parent account is used in the route.
Raises :Http400 if the requesting user does not have access to all accounts provided in the request body.
Raises :Http401 if the requesting user is trying to edit a user with an equal or higher role.

Sample Response [showhide]
GET /100/enterprise/name@myemma.com/subaccounts
    "message": true

Related Topics

Interested in Emma?

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