Emma API Documentation

Mailings

With these endpoints, you can get information about your mailings including their HTML contents. You can retrieve the members to whom the mailing was sent. You can also pause mailings and cancel mailings that are pending or paused.

GET /#account_id/mailings

Get information about current mailings.

Parameters:
  • include_archived (boolean) – Optional flag to include archived mailings in the list.
  • mailing_types (string) – Optional parameter that accepts a comma-separated string with one or more of the following mailing types: ‘m’ (standard), ‘t’ (test), ‘r’ (trigger), ‘s’ (subject line split test), ‘c’ (content split test). Defaults to ‘m,t’, standard and test mailings, when none are specified.
  • mailing_statuses (string) – Optional parameter that accepts a comma-separated string with one or more of the following mailing statuses: ‘p’ (pending), ‘a’ (paused), ‘i’ (injecting), ‘s’ (sending), ‘x’ (canceled), ‘c’ (complete), ‘w’ (waiting), ‘u’ (unapproved), ‘f’ (failed). Defaults to ‘p,a,i,s,x,c,w,u,f’, all statuses, when none are specified.
  • is_scheduled (boolean) – Optional flag for mailings that have a scheduled timestamp.
  • with_html_body (boolean) – Optional flag to include the html_body content.
  • with_plaintext (boolean) – Optional flag to include the plaintext content.
Raises :

Http400 if invalid mailing types or statuses are specified.

Returns :

An array of mailings.

Sample Response [showhide]
GET /100/mailings

[
  {
    "mailing_type": "m",
    "send_started": null,
    "cancel_by_user_id": null,
    "mailing_id": 201,
    "recipient_count": 0,
    "cancel_ts": null,
    "mailing_status": "p",
    "month": null,
    "failure_ts": null,
    "reply_to": null,
    "year": null,
    "datacenter": null,
    "started_or_finished": null,
    "account_id": 100,
    "disabled": false,
    "created_ts": "@D:2013-08-22T09:41:45",
    "sender": "Kevin McConnell",
    "plaintext_only": false,
    "name": "Cancellable mailing",
    "parent_mailing_id": null,
    "failure_message": null,
    "send_finished": null,
    "send_at": null,
    "signup_form_id": null,
    "subject": "Cancellable mailing",
    "purged_at": null,
    "archived_ts": null
  },
  {
    "mailing_type": "m",
    "send_started": null,
    "cancel_by_user_id": null,
    "mailing_id": 200,
    "recipient_count": 0,
    "cancel_ts": null,
    "mailing_status": "c",
    "month": null,
    "failure_ts": null,
    "reply_to": null,
    "year": null,
    "datacenter": null,
    "started_or_finished": null,
    "account_id": 100,
    "disabled": false,
    "created_ts": "@D:2013-08-22T09:41:45",
    "sender": "Kevin McConnell",
    "plaintext_only": false,
    "name": "Sample Mailing",
    "parent_mailing_id": null,
    "failure_message": null,
    "send_finished": null,
    "send_at": null,
    "signup_form_id": null,
    "subject": "Sample Mailing for [% member:first_name %] [% member:last_name %]",
    "purged_at": null,
    "archived_ts": null
  }
]

Sample Response [showhide]
GET /100/mailings?mailing_statuses=p,c&mailing_types=m,t

[
  {
    "mailing_type": "m",
    "send_started": null,
    "cancel_by_user_id": null,
    "mailing_id": 201,
    "recipient_count": 0,
    "cancel_ts": null,
    "mailing_status": "p",
    "month": null,
    "failure_ts": null,
    "reply_to": null,
    "year": null,
    "datacenter": null,
    "started_or_finished": null,
    "account_id": 100,
    "disabled": false,
    "created_ts": "@D:2013-08-22T09:41:45",
    "sender": "Kevin McConnell",
    "plaintext_only": false,
    "name": "Cancellable mailing",
    "parent_mailing_id": null,
    "failure_message": null,
    "send_finished": null,
    "send_at": null,
    "signup_form_id": null,
    "subject": "Cancellable mailing",
    "purged_at": null,
    "archived_ts": null
  },
  {
    "mailing_type": "m",
    "send_started": null,
    "cancel_by_user_id": null,
    "mailing_id": 200,
    "recipient_count": 0,
    "cancel_ts": null,
    "mailing_status": "c",
    "month": null,
    "failure_ts": null,
    "reply_to": null,
    "year": null,
    "datacenter": null,
    "started_or_finished": null,
    "account_id": 100,
    "disabled": false,
    "created_ts": "@D:2013-08-22T09:41:45",
    "sender": "Kevin McConnell",
    "plaintext_only": false,
    "name": "Sample Mailing",
    "parent_mailing_id": null,
    "failure_message": null,
    "send_finished": null,
    "send_at": null,
    "signup_form_id": null,
    "subject": "Sample Mailing for [% member:first_name %] [% member:last_name %]",
    "purged_at": null,
    "archived_ts": null
  }
]

GET /#account_id/mailings/#mailing_id

Get detailed information for one mailing.

Parameters:
  • include_segment_names (boolean) – Optional flag to include segment names under recipient_segments. False by default.
  • include_subscription_names (boolean) – Optional flag to include subscription names under recipient_subscriptions. False by default.
Returns :A mailing.
Raises :Http404 if no mailing is found.

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

{
  "recipient_groups": [
    {
      "member_group_id": 151,
      "name": "Widget Buyers"
    }
  ],
  "recipient_subscriptions": [
    {
      "subscription_id": 200,
      "subscription_name": "Widgets"
    }
  ],
  "heads_up_emails": [],
  "send_started": null,
  "signup_form_id": null,
  "links": [
    {
      "mailing_id": 200,
      "plaintext": false,
      "link_id": 200,
      "link_name": "Emma",
      "link_target": "http://www.myemma.com",
      "link_order": 1
    }
  ],
  "mailing_id": 200,
  "plaintext": "Hello [% member:first_name %]!",
  "recipient_count": 0,
  "public_webview_url": "http://localhost/webview/uf/6db0cc7e6fdb2da589b65f29d90c96b6",
  "mailing_type": "m",
  "recipient_segments": [],
  "parent_mailing_id": null,
  "recipient_searches": [],
  "deleted_at": null,
  "account_id": 100,
  "recipient_members": [
    {
      "email": "youremma@myemma.com",
      "member_id": 200
    }
  ],
  "mailing_status": "c",
  "sender": "Kevin McConnell",
  "name": "Sample Mailing",
  "send_finished": null,
  "send_at": null,
  "reply_to": null,
  "subject": "Sample Mailing for [% member:first_name %] [% member:last_name %]",
  "archived_ts": null,
  "html_body": "<p>Hello [% member:first_name %]!</p>"
}

GET /#account_id/mailings/#mailing_id/members

Get the list of members to whom the given mailing was sent. This does not include groups or searches.

Returns :An array of members including status and member fields.
Raises :Http404 if no mailing is found.

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

[
  {
    "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": "youremma@myemma.com"
  }
]

GET /#account_id/mailings/#mailing_id/messages/#member_id

Gets the personalized message content as sent to a specific member as part of the specified mailing.

Parameters:
  • type (string) – Accepts: ‘all’, ‘html’, ‘plaintext’, ‘subject’, ‘webview_url’. Defaults to ‘all’, if not provided.
Returns :

Message content from a mailing, personalized for a member. The response will contain all parts of the mailing content by default, or just the type of content specified by type.

Raises :

Http404 if no message is found.

Raises :

Http500 if allowed_types is not valid.

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

{
  "plaintext": "Hello !",
  "subject": "Sample Mailing for  ",
  "html_body": "<p>Hello !</p>",
  "webview_url": "https://tracker/message/200/200"
}

Sample Response [showhide]
GET /100/mailings/200/messages/200?type=html

{
  "html_body": "<p>Hello !</p>"
}

GET /#account_id/mailings/#mailing_id/groups

Get the groups to which a particular mailing was sent.

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

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

[
  {
    "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"
  }
]

GET /#account_id/mailings/#mailing_id/subscriptions

Get the subscriptions to which a particular mailing was sent.

Returns :An array of subscriptions.
Raises :Http404 if no mailing is found.

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

[
  {
    "subscription_name": "Widgets",
    "account_id": 100,
    "member_count": 100,
    "settings": {
      "show_on_default_preference_form": false
    },
    "created_at": "Mon, 22 Jul 2019 18:45:47 GMT",
    "description": "Widgets Subscription",
    "modified_at": "Mon, 22 Jul 2019 18:45:47 GMT",
    "optout_count": 0,
    "subscription_id": 300
  }
]

GET /#account_id/mailings/#mailing_id/searches

Get all searches associated with a sent mailing.

Returns :An array of searches.
Raises :Http404 if no mailing is found.

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

[
  {
    "optout_count": 0,
    "account_id": 100,
    "cached_at": null,
    "last_run_at": "@D:2018-02-06T16:27:06",
    "active_count": 4,
    "error_count": 0,
    "criteria": "["and", ["and", ["member_field:name_first", "contains", "*Kevin*"]]]",
    "deleted_at": null,
    "purged_at": null,
    "search_id": 400,
    "name": "All the Kevins"
  }
]

GET /#account_id/mailings/#mailing_id/suppressed_searches

Get all suppressed searches associated with a sent mailing.

Returns :An array of suppressed searches.
Raises :Http404 if no mailing is found.

Sample Response [showhide]
GET|/100/mailings/200/suppressed_searches

[
  {
    "optout_count": 0,
    "account_id": 200,
    "cached_at": "@D:2018-08-13T14:28:12",
    "last_run_at": "@D:2018-08-13T14:28:12",
    "active_count": 772,
    "error_count": 0,
    "criteria": "["and", ["and", ["not", ["opened", "in last", {"week": "52"}]]]]",
    "deleted_at": null,
    "purged_at": null,
    "search_id": 401,
    "name": "Inactive 12+ Months"
  }
]

GET /#account_id/mailings/#mailing_id/suppressed_members

Get all suppressed members for a particular mailing.

Returns :An array of suppressed members.
Raises :Http404 if no mailing is found.

Sample Response [showhide]
GET|/100/mailings/200/suppressed_members

[
  {
    "status": "active",
    "confirmed_opt_in": null,
    "account_id": 100,
    "fields": {
        "first_name": "Kevin",
        "last_name": "McConnell,"
    },
    "member_id": 200,
    "last_modified_at": "@D:2017-05-09T08:14:30",
    "member_status_id": "a",
    "plaintext_preferred": false,
    "email_error": null,
    "member_since": "@D:2017-05-09T08:14:30",
    "bounce_count": 0,
    "deleted_at": null,
    "email": "youremma@myemma.com"
  },
  {
    "status": "active",
    "confirmed_opt_in": null,
    "account_id": 100,
    "fields": {
        "first_name": "Emma",
        "last_name": "Smith"
    },
    "member_id": 201,
    "last_modified_at": "@D:2017-05-09T08:14:30",
    "member_status_id": "a",
    "plaintext_preferred": false,
    "email_error": null,
    "member_since": "@D:2017-05-09T08:14:30",
    "bounce_count": 0,
    "deleted_at": null,
    "email": "theiremma@myemma.com"
  },
]

PUT /#account_id/mailings/#mailing_id

Update status of a current mailing

The status can be one of canceled, paused or ready. This method can be used to control the progress of a mailing by pausing, canceling or resuming it. Once a mailing is canceled it can’t be resumed, and will not show in the normal mailing_list output.

Parameters:
  • status (string) – Accepts ‘canceled’, ‘paused’ or ‘ready’.
Raises :Http404 if no mailing is found.
Raises :Http400 if the mailing is already in Completed or Sending status and cannot be updated.
Raises :Http400 if the mailing is in Pending or Unapproved status and the html or plaintext is missing a required tag.
Raises :Http400 if the mailing is in Pending or Unapproved status and cannot be rescheduled.
Raises :Http400 if an invalid status is passed in.
Raises :Http400 if the mailing is already canceled.
Returns :The updated mailing
DELETE /#account_id/mailings/#mailing_id

Sets archived timestamp for a mailing so it is no longer included in mailing_list.

Returns :True if the mailing is successfully archived.

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

true

DELETE /#account_id/mailings/cancel/#mailing_id

Cancels a mailing that has a current status of pending or paused. All other statuses will result in a 403.

Returns :True if mailing marked as cancelled.
Raises :Http403 if the current mailing status is not pending or paused.
Raises :Http404 if no mailing is found.

Sample Response [showhide]
DELETE /100/mailings/cancel/201

true

POST /#account_id/forwards/#mailing_id/#member_id

Forward a previous message to additional recipients. If these recipients are not already in the audience, they will be added with a status of FORWARDED.

Parameters:
  • heads_up_emails (array) – An array of email addresses that heads up notification emails will be sent to.
  • recipient_emails (array) – An array of email addresses to which to forward the specified message.
Returns :

A reference to the new mailing_id.

Raises :

Http404 if no message is found.

Sample Response [showhide]
POST /100/forwards/200/200
{
  "recipient_emails": [
    "alex@myemma.com",
    "chris@myemma.com"
  ]
}

{
  "mailing_id": 1024
}

POST /#account_id/mailings/#mailing_id

Send a prior mailing to additional recipients. A new mailing will be created that inherits its content from the original.

Parameters:
  • sender (string) – The message sender. If this is not supplied, the sender of the original mailing will be used.
  • heads_up_emails (array) – An array of email addresses that heads up notification emails will be sent to.
  • recipient_emails (array) – An array of email addresses to which the new mailing should be sent.
  • recipient_groups (array) – An array of member groups to which the new mailing should be sent.
  • recipient_subscriptions (array) – An array of subscriptions to which the new mailing should be sent.
  • recipient_searches (array) – An array of searches that this mailing should be sent to.
  • recipient_segments (array) – An array of segments that this mailing should be sent to.
  • suppression_segments (array) – An array of suppressed segments that this mailing should not be sent to.
Returns :

A reference to the new mailing_id.

Raises :

Http404 if no mailing is found.

Sample Response [showhide]
POST /100/mailings/200
{
  "recipient_emails": [
    "michelle@myemma.com"
  ]
}

{
  "mailing_id": 1024
}

GET /#account_id/mailings/#mailing_id/headsup

Get heads up email address(es) related to a mailing.

Returns :An array of heads up email addresses.
Raises :Http404 if no mailing is found.

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

[
  {
    "sent_ts": null,
    "email": "myemma@myemma.com",
    "mailing_id": 200
  },
  {
    "sent_ts": null,
    "email": "youremma@myemma.com",
    "mailing_id": 200
  }
]

POST /#account_id/mailings/validate

Validate that a mailing has valid personalization-tag syntax. Checks tag syntax in three params:

Parameters:
  • html_body (string) – Optional html contents of the mailing.
  • plaintext (string) – Optional plaintext contents of the mailing.
  • subject (string) – Optional subject of the mailing.
Returns :

true

Raises :

Http400 if any tags are invalid. The response body will have information about the invalid tags.

Sample Response [showhide]
POST /100/mailings/validate
{
  "subject": "Another Fine Test"
}

true

POST /#account_id/mailings/#mailing_id/winner/#winner_id

Declare the winner of a split test manually. In the event that the test duration has not elapsed, the current stats for each test will be frozen and the content defined in the user declared winner will sent to the remaining members for the mailing. Please note, any messages that are pending for each of the test variations will receive the content assigned to them when the test was initially constructed.

Returns :True on success.
Raises :Http403 if the winner cannot be manually declared.
Raises :Http404 if the mailing is not found.
Raises :Http404 if the winning_id mailing is not found.

Sample Response [showhide]
POST /100/mailings/202/winner/203
{}

true

Related Topics

Interested in Emma?

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