Emma API Documentation

Subscriptions

Using these endpoints you can create, edit, delete and get information about subscriptions in your account.

GET /#account_id/subscriptions

Get a list of all subscriptions in an account.

Parameters:
  • deleted_only – true or false. Returns deleted subscriptions only. Optional, defaults to false.
  • include_deleted – true or false. Returns deleted subscriptions along with active. Optional, defaults to false.
Returns:

A list of subscriptions in an account along with related information, including member count and subscription ID.

Sample Response [showhide]
GET /100/subscriptions

[
  {
    "account_id": 100,
    "created_at": "Mon, 01 Apr 2019 18:40:58 GMT",
    "deleted_at": null,
    "description": "Company updates and news",
    "import_status": null,
    "member_count": 984,
    "modified_at": "Mon, 01 Apr 2019 18:40:58 GMT",
    "optout_count": 1,
    "purged_at": null,
    "settings": {
      "show_on_default_preference_form": true
    },
    "subscription_id": 1,
    "subscription_name": "General News",
    "subscription_order": 1
  }
]

GET /#account_id/subscriptions/subscription_id

Get detailed information for a specific subscription.

Returns:Information about a subscription.

Sample Response [showhide]
GET /100/subscriptions/200

{
    "account_id": 100,
    "created_at": "Wed, 25 Sep 2019 21:39:34 GMT",
    "deleted_at": null,
    "description": "Regularly donate $1,500 or more.",
    "member_count": 0,
    "modified_at": "Wed, 25 Sep 2019 21:39:34 GMT",
    "optout_count": 0,
    "purged_at": null,
    "settings": null,
    "subscription_id": 200,
    "subscription_name": "Gold-Level Donors",
    "subscription_order": null
}

GET /#account_id/subscriptions/#subscription_id/members

Get a list of member IDs for members subscribed to a specific subscription.

Parameters:
  • start – Defaults to 0 if not specified.
  • end – Defaults to 500 if not specified.
Returns:A list of member IDs.

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

[
  {
    "member_id": 1
  },
  {
    "member_id": 2
  },
  {
    "member_id": 3
  },
  {
    "member_id": 4
  }
]

GET /#account_id/subscriptions/#subscription_id/optouts

Get a list of member IDs for members who have opted out of a specific subscription.

Parameters:
  • start – Defaults to 0 if not specified.
  • end – Defaults to 500 if not specified.
Returns:A list of member IDs.

Sample Response [showhide]
GET /100/subscriptions/200/optouts

[
    {
        "member_id": 5
    },
    {
        "member_id": 6
    },
    {
        "member_id": 7
    },
    {
        "member_id": 8
    }
]

POST /#account_id/subscriptions

Create a subscription.

Parameters:
  • name (string) – Required. Names the subscription, and will be visible in the Subscription Center.
  • description (string) – Describes the subscription, and will be visible in the Subscription Center.
Returns:

Information about the created subscription, including the subscription ID.

Sample Response [showhide]
    POST /100/subscriptions

    {
        "name": "Cat Fanatics",
        "description": "Cat-only newsletter subscribers"
    }

    {
        "account_id": 100,
        "created_at": "Wed, 25 Sep 2019 21:39:34 GMT",
        "deleted_at": null,
        "description": "Cat-only newsletter subscribers",
        "member_count": 0,
        "modified_at": "Wed, 25 Sep 2019 21:39:34 GMT",
        "optout_count": 0,
        "purged_at": null,
        "settings": null,
        "subscription_id": 300,
        "subscription_name": "Cat Fanatics",
        "subscription_order": null
    }
    

POST /#account_id/subscriptions/#subscription_id/members/bulk

Bulk subscribe members to a subscription using either a list of member IDs or a single import ID.

Returns:True if successful.

Sample Response [showhide]
        POST /100/subscriptions/200/members/bulk
        {
            "member_ids": [1, 2, 3, 4]
        }

        true
    

Sample Response [showhide]
        POST /100/subscriptions/200/members/bulk
        {
            "import_id": 1
        }

        true
    

PUT /#account_id/subscriptions/#subscription_id

Edit a subscription's name or description.

Parameters:
  • name (string) – Only required if updating the name. Visible in the Subscription Center.
  • description (string) – Describes the subscription, and is visible in the Subscription Center.
Returns:

Information about the updated subscription.

Sample Response [showhide]
    PUT /100/subscriptions/300
    {
        "name": "Cat Fanatics Only",
        "description": "A newsletter for those only interested in cat products"
    }

    {
        "account_id": 100,
        "created_at": "Wed, 25 Sep 2019 21:39:34 GMT",
        "deleted_at": null,
        "description": "A newsletter for those only interested in cat products",
        "member_count": 0,
        "modified_at": "Fri, 27 Sep 2019 21:43:22 GMT",
        "optout_count": 0,
        "purged_at": null,
        "settings": null,
        "subscription_id": 300,
        "subscription_name": "Cat Fanatics Only",
        "subscription_order": null
    }

DELETE /#account_id/subscriptions/subscription_id

Delete a subscription.

Returns:Information about the subscription, including the date and time it was deleted.

Sample Response [showhide]
    DELETE /100/subscriptions/200

    {
        "account_id": 100,
        "created_at": "Wed, 25 Sep 2019 21:39:34 GMT",
        "deleted_at": "Thu, 26 Sep 2019 20:29:33 GMT",
        "description": "Regularly donate $1,500 or more.",
        "member_count": 150,
        "modified_at": "Wed, 25 Sep 2019 21:39:34 GMT",
        "optout_count": 8,
        "purged_at": null,
        "settings": null,
        "subscription_id": 200,
        "subscription_name": "Gold-Level Donors",
        "subscription_order": null
    }

Related Topics

Interested in Emma?

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