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

Emma API Documentation

Mailings¶

Related Topics

Emma Links

Interested in Emma?

Navigation

Mailings¶

Related Topics

Quick search

Emma Links

Interested in Emma?