Autoresponders

Remote Lists

Autoresponders are not available on Remote Lists. API calls to these endpoints will return an error message if attempted on a Remote List.

Get a list of autoresponders

Get a list of the basic details of all autoresponders of a particular mailing list.

URL

GET /ga/api/v2/mailing_lists/:mailing_list_id/autoresponders

Request Parameters

This API method does not require any additional parameters.

Response

The response will be a JSON array where each element contains the following keys.

Key Meaning Example Type
id The autoresponder's internal ID 1234 Integer
mailing_list_id The mailing list ID 99182 Integer
name The name of the autoresponder "On Subscription" String
paused This autoresponder is paused true Boolean
trigger The type of action that this autoresponder triggers on "subscription", "campaign_open", "autoresponder_open", "autoresponder_nonopen", "autoresponder_send" String
delay Indicate whether or not this autoresponder is delayed "immediately", "with_delay" String
delay_amount The number of units to delay this autoresponder 12345 Integer
delay_unit The time unit to delay the autoresponder "minutes", "hours", "days", "weeks", "months" String
delay_time For "days", "weeks", and "months" -- this field determines the hour of day at which the autoresponder will run 12 (For 12pm), 23 (For 11pm) Integer
trigger_include_subscribers_from_import Determines if this autoresponder should run on subscribers added in imports false Boolean
trigger_run_on_api Determines if this autoresponder should run on subscribers created via the API true Boolean
trigger_campaign_to_open_id The ID of the campaign that when opened will cause this autoresponder to trigger. Only valid if trigger is equal to campaign_open. null Integer
trigger_autoresponder_to_open_id The ID of the autoresponder that when opened (or not opened) will cause this autoresponder to trigger. Only valid if trigger is equal to autoresponder_open or autoresponder_nonopen. 123 Integer
use_external_delivery_setting This autoresponder uses the mailing list's web form delivery settings false Boolean
bounce_email_user_id The bounce email's user_id component 1 Integer
bounce_email_domain_id The bounce email's domain_id component 2 Integer
from_name Emails from this autoresponder will be sent using this from_name "bob@example.com" String
from_email Emails from this autoresponder will be sent using this from_email "Bob Example" String
virtual_mta_id Emails from this autoresponder will be sent using this Virtual MTA 123 Integer
url_domain_id Emails from this autoresponder will be sent using this URL Domain 456 Integer
track_opens Track open statistics on this autoresponder false Boolean
track_links Track click statistics on this autoresponder true Boolean
content_subject The subject to use in emails "both" String
content_format Email format for this autoresponder's messages "Message Inside!" String
content_html The HTML content for this autoresponder "Hello, <b>world</b>!" String
content_text The plain-text content for this autoresponder "Hello, world!" String
triggered_on The time this autoresponder last triggered "2013-01-01T00:00:00Z" String
paused_at The time at which this autoresponder was paused "2013-01-01T00:00:00Z" String
segmentation_criteria_id The segmentation criteria used to filter messages sent for this autoresponder 123 Integer
special_sending_rule_id The ID of the special sending rule used for this autoresponder. 123 Integer
special_sending_rule_name The name of the special sending rule used for this autoresponder. "Customize Content" String

Example Request

> GET /ga/api/mailing_lists/1/autoresponders HTTP/1.1
> Authorization: Basic MToxNmRjYjllYmM1MzE1M2Q3YWViOTQ3YmE0MGE3NDVkMzc4N2ViYWJj
> Accept: application/json
> Content-Type: application/json
< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "9323c826bfdca52cecc77fdd770790df"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: ["_session_id=8126d0dfecae8e434cf92a0e0571cc24; path=/; HttpOnly", "request_method=; path=/; expires=Thu, 01-Jan-1970 00:00:00 GMT"]
< X-Request-Id: afa3201c968634aa6eef172f9dec0dff
< X-Runtime: 0.054517
< Connection: close
< Server: thin
{
  "success": true,
  "data": [
    {
      "bounce_email_domain_id": null,
      "bounce_email_user_id": null,
      "delay": "immediately",
      "delay_amount": 0,
      "delay_time": 0,
      "delay_unit": null,
      "from_email": null,
      "from_name": null,
      "id": 1,
      "mailing_list_id": 1,
      "name": "Subscription Autoresponder #1",
      "paused": true,
      "paused_at": null,
      "segmentation_criteria_id": 1,
      "track_links": true,
      "track_opens": true,
      "trigger": "subscription",
      "trigger_autoresponder_to_open_id": null,
      "trigger_campaign_to_open_id": null,
      "trigger_include_subscribers_from_import": true,
      "trigger_run_on_api": true,
      "triggered_on": null,
      "url_domain_id": null,
      "use_external_delivery_setting": true,
      "virtual_mta_id": null,
      "special_sending_rule_id": null,
      "special_sending_rule_name": null,
      "content_subject": "Welcome to my list!",
      "content_format": "both",
      "content_html": "<!DOCTYPE html>\r\n<html>\r\n<head>\r\n</head>\r\n<body>\r\n<p>I'm so pleased you could join us.</p>\r\n</body>\r\n</html>",
      "content_text": "foo bar"
    },
    {
      "bounce_email_domain_id": 1,
      "bounce_email_user_id": 1,
      "delay": "with_delay",
      "delay_amount": 30,
      "delay_time": 0,
      "delay_unit": "minutes",
      "from_email": "sender@discardallmail.inboxfirst.com",
      "from_name": "Studio Sender",
      "id": 2,
      "mailing_list_id": 1,
      "name": "Campaign Open Autoresponder",
      "paused": true,
      "paused_at": null,
      "segmentation_criteria_id": 2,
      "track_links": true,
      "track_opens": true,
      "trigger": "campaign_open",
      "trigger_autoresponder_to_open_id": null,
      "trigger_campaign_to_open_id": 1,
      "trigger_include_subscribers_from_import": false,
      "trigger_run_on_api": false,
      "triggered_on": null,
      "url_domain_id": 1,
      "use_external_delivery_setting": false,
      "virtual_mta_id": 0,
      "special_sending_rule_id": null,
      "special_sending_rule_name": null,
      "content_subject": "You opened my campaign!",
      "content_format": "html",
      "content_html": "<!DOCTYPE html>\r\n<html>\r\n<head>\r\n</head>\r\n<body>\r\n<p>I hope you liked it.</p>\r\n</body>\r\n</html>",
      "content_text": ""
    }
  ],
  "error_code": null,
  "error_message": null
}

Create a new autoresponder

Create a new autoresponder on the specified mailing list.

URL

POST /ga/api/v2/mailing_lists/:mailing_list_id/autoresponders

Request Parameters

The request body should be a JSON hash in the format of { 'autoresponder': AUTORESPONDER_DETAILS } where AUTORESPONDER_DETAILS is defined above in the Get a list of autoresponders section.

Note that you may provide only one of special_sending_rule_id and special_sending_rule_name.

Response

The response will be a JSON object in the same format as the response to the autoresponders index.

Example Request

Note that the JSON response will not be "pretty formatted" as it is below.

> POST /ga/api/mailing_lists/1/autoresponders HTTP/1.1
> Authorization: Basic MToxNmRjYjllYmM1MzE1M2Q3YWViOTQ3YmE0MGE3NDVkMzc4N2ViYWJj
> Accept: application/json
> Content-Type: application/json
{
  "autoresponder": {
    "bounce_email_domain_id": 1,
    "bounce_email_user_id": 1,
    "delay": "immediately",
    "delay_amount": 0,
    "delay_time": 0,
    "delay_unit": null,
    "from_email": "bob@example.com",
    "from_name": "Bob Example",
    "name": "Autoresponder 2",
    "paused": false,
    "paused_at": null,
    "segmentation_criteria_id": 1,
    "track_links": true,
    "track_opens": true,
    "trigger": "subscription",
    "trigger_campaign_to_open_id": null,
    "trigger_include_subscribers_from_import": false,
    "trigger_run_on_api": false,
    "triggered_on": "2014-06-30",
    "url_domain_id": 1,
    "use_external_delivery_setting": true,
    "virtual_mta_id": 0,
    "content_format": "html",
    "content_subject": "Welcome to our mailing list!",
    "content_html": "<p>Welcome!</p>",
    "special_sending_rule_id":123,
    "special_sending_rule_name":"Customize Content"
  }
}
< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "d5361297bdcff3a922bfe56d5f2398ad"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: ["request_method=POST; path=/", "_session_id=4851f080c4908bd8fbe3809de3146c8d; path=/; HttpOnly"]
< X-Request-Id: bdc5494afb378e0e6aac27adf21ffd9f
< X-Runtime: 0.171395
< Connection: close
< Server: thin
{
  "success": true,
  "data": {
    "bounce_email_domain_id": null,
    "bounce_email_user_id": null,
    "delay": "immediately",
    "delay_amount": 0,
    "delay_time": 0,
    "delay_unit": null,
    "from_email": null,
    "from_name": null,
    "id": 3,
    "mailing_list_id": 1,
    "name": "Autoresponder 2",
    "paused": false,
    "paused_at": null,
    "segmentation_criteria_id": 1,
    "track_links": true,
    "track_opens": true,
    "trigger": "subscription",
    "trigger_autoresponder_to_open_id": null,
    "trigger_campaign_to_open_id": null,
    "trigger_include_subscribers_from_import": false,
    "trigger_run_on_api": false,
    "triggered_on": null,
    "url_domain_id": null,
    "use_external_delivery_setting": true,
    "virtual_mta_id": null,
    "special_sending_rule_id":92,
    "special_sending_rule_name":"Customize Content",
    "content_subject": "Welcome to our mailing list!",
    "content_format": "html",
    "content_html": "<h1>Welcome!</h1>",
    "content_text": ""
  },
  "error_code": null,
  "error_message": null
}

Update an existing autoresponder

Update an existing autoresponder.

URL

PUT /ga/api/v2/mailing_lists/:mailing_list_id/autoresponders/:id

Request Parameters

The request body for updating a subscriber is in the same format as the one declared above for creating a new autoresponder.

Response

The response will be a JSON object in the same format as the response to the autoresponders index.

Example Request

Note that the JSON response will not be "pretty formatted" as it is below.

> PUT /ga/api/mailing_lists/1/autoresponders/1 HTTP/1.1
> Authorization: Basic MToxNmRjYjllYmM1MzE1M2Q3YWViOTQ3YmE0MGE3NDVkMzc4N2ViYWJj
> Accept: application/json
> Content-Type: application/json
{
  "autoresponder": {
    "from_email": "sender@example.com",
    "content_text": "foo bar"
  }
}
< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "b85e60d89386b93deb04dca295faed38"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: ["request_method=PUT; path=/", "_session_id=b8f57f23aeed1f8789cf890813e6805c; path=/; HttpOnly"]
< X-Request-Id: a8569a929868290a1c713285ebe1731a
< X-Runtime: 0.108229
< Connection: close
< Server: thin
{
  "success": true,
  "data": {
    "bounce_email_domain_id": null,
    "bounce_email_user_id": null,
    "delay": "immediately",
    "delay_amount": 0,
    "delay_time": 0,
    "delay_unit": null,
    "from_email": null,
    "from_name": null,
    "id": 1,
    "mailing_list_id": 1,
    "name": "Subscription Autoresponder #1",
    "paused": true,
    "paused_at": null,
    "segmentation_criteria_id": 1,
    "track_links": true,
    "track_opens": true,
    "trigger": "subscription",
    "trigger_autoresponder_to_open_id": null,
    "trigger_campaign_to_open_id": null,
    "trigger_include_subscribers_from_import": true,
    "trigger_run_on_api": true,
    "triggered_on": null,
    "url_domain_id": null,
    "use_external_delivery_setting": true,
    "virtual_mta_id": null,
    "special_sending_rule_id": null,
    "special_sending_rule_name": null,
    "content_subject": "Welcome to my list!",
    "content_format": "both",
    "content_html": "<!DOCTYPE html>\r\n<html>\r\n<head>\r\n</head>\r\n<body>\r\n<p>I'm so pleased you could join us.</p>\r\n</body>\r\n</html>",
    "content_text": "foo bar"
  },
  "error_code": null,
  "error_message": null
}

Get statistics for an autoresponder

URL

GET /ga/api/v2/mailing_lists/:mailing_list_id/autoresponders/:id/statistics
GET /ga/api/v2/mailing_lists/:mailing_list_id/autoresponders/:id/statistics?start_date=20140302&end_date=20140401

Request Parameters

Key Meaning Example
mailing_list_id The id of the mailing list the subscribers are on. This can be found on the mailing list's page under the Admin section 456
id The id of the autoresponder 12345
start_date The earliest date that email was sent for the requested statistics. The result will include statistics for emails sent on this date. This can be blank. 20140403 (YYYYMMDD)
end_date The latest date that email was sent for the requested statistics. The result will include statistics for emails sent on this date. This can be blank. 20140403 (YYYYMMDD)

Response

duplicate_unsubs
integer
sent_text
integer
Number of recipients that were sent a text-only message.
sent_html
integer
Number of recipients that were sent a html-only message.
sent_multipart
integer
Number of recipients that were sent a multipart message.
messages_sent
integer
Total number of recipients.
messages_html
integer
Number of recipients that received either an HTML or multipart message.
messages_text
integer
Number of recipients that received a text-only message.
bounces_total
integer
Total number of bounces received.
bounces_unique
integer
Unique (by subscriber) bounces received.
bounces_unique_hard
integer
Number of unique (by subscriber) bounces where bounce_type is hard.
bounces_unique_soft
integer
Number of unique (by subscriber) bounces where bounce_type is soft.
bounces_unique_other
integer
Number of unique (by subscriber) bounces where bounce_type is other.
bounces_unique_local
integer
Number of unique (by subscriber) bounces that were local.
bounces_unique_remote
integer
Number of unique (by subscriber) bounces that were remote.
bounces_status_updated
integer
Number of recipients where status was updated to status 'bounce' (See 1 below).
bounces_unique_by_code
hash
Number of unique (by subscriber) bounces for each bounce code. The keys in the included hash are the bounce code.
bounced
integer
Deprecated: Unique (by subscriber) bounces received. This is just another name for bounces_unique.
duplicate_bounces
integer
Number of non-unique bounces.
unbounced
integer
Number of messages that were sent that have not bounced.
bounce_rate
float
Floating point value indicating the unique bounce rate for this autoresponder. This value ranges from 0.0 to 1.0.
bounce_rate_hard
float
The ratio of the unique bounces that were hard bounces. This value ranges from 0.0 to 1.0.
bounce_rate_soft
float
The ratio of the unique bounces that were soft bounces. This value ranges from 0.0 to 1.0.
bounce_rate_other
float
The ratio of the unique bounces that were other bounces. This value ranges from 0.0 to 1.0.
bounce_local_rate
float
The ratio of the unique bounces that were local bounces. This value ranges from 0.0 to 1.0.
clicks_total
integer
Number of total clicks.
clicks_unique
integer
Number of unique clicks (unique by subscriber).
clicks_unique_by_link
integer
Deprecated: Number of unique clicks (unique by subscriber/link) -- this value does not carry much meaning.
duplicate_clicks
integer
Number of non-unique clicks.
click_rate
float
The ratio of messages that were accepted and have been clicked. This value ranges from 0.0 to 1.0.
click_to_open_rate
float
The ratio of messages that were opened that have been clicked. This value ranges from 0.0 to 1.0.
unclicked
integer
Number of messages that were accepted by the remote server but have not been clicked.
opens_total
integer
Number of total opens
opens_unique
integer
Number of unique opens (unique by subscriber)
open_rate
float
Ratio of messages that were accepted that have been opened. This value ranges from 0.0 to 1.0.
open_ratio
float
Average number of times each opened message has been opened (opens_total / opens_unique). This value ranges from 0.0 to 1.0.
unopened
integer
Number of messages that were accepted and have not been opened.
duplicate_opens
integer
Number of non-unique opens.
scomps_total
integer
Number of spam complaints
scomps_unique
integer
Number of unique spam complaints (unique by subscriber).
scomps_status_updated
integer
Number of recipients where the status was updated to status 'scomp' (See 1 below).
duplicate_scomps
integer
Number of non-unique spam complaints.
unsubs_total
integer
Number of total unsubscribes
unsubs_unique
integer
Number of unique unsubscribes (unique by subscriber)
unsubs_status_updated
integer
Number of recipients where the status was updated to status 'unsubscribed' (See 1 below).
Number of non-unique unsubscribes.
unsub_rate
float
The ratio of messages that were accepted and unsubscribed. This value ranges from 0.0 to 1.0.
skips_error
integer
Number of messages that were skipped due to a Special Sending Rule error.
skips_request
integer
Number of messages that were skipped due to a Special Sending Rule request.
total_messages
integer
Total number of messages injected for this autoresponder.
total_success
integer
Number of messages that were successfully delivered to the remote server.
total_failure
integer
Number of messages ended due to SMTP conversation failures.
total_failure_toolong
integer
Number of messages ended due to being in the queue too long.
accepted
integer
Total number of messages that were accepted by the remote server.
accepted_rate
float
Ratio of messages that were attempted and accepted (accepted / messages_sent). This value ranges from 0.0 to 1.0.
in_queue
integer
Number of messages that are currently in InboxFirst Engine's delivery queue.
in_queue_rate
float
Ratio of the total number of messages that have been handed off to InboxFirst Engine and are still in queue. This value ranges from 0.0 to 1.0.
max_unique_activities
integer
The max value of opens_unique, clicks_unique, unsubs_unique, and scomps_unique.
  1. The status updated fields will always be 0 on Remote Lists.

Example Request

> GET /ga/api/v2/mailing_lists/1/autoresponders/1/statistics HTTP/1.1
> Authorization: Basic MTo1ZTk2NDY1Yzg4M2YzMzA5ZjAxMDVhMmUxMDc2NjMyYjY4N2U2MWQy
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8r zlib/1.2.5
> Host: inboxfirst.dev
> Accept: */*
>
< HTTP/1.1 200 OK
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< Set-Cookie: _session_id=458055a23f26f844e74f8cd7300f6445; path=/; HttpOnly
< X-Request-Id: f6e40d578ed1d9c418cca45e1b7fe532
< X-Runtime: 0.025540
< Connection: close
{
   "success":true,
   "data":{
      "sent_text":3,
      "sent_html":137,
      "sent_multipart":137,
      "bounces_total":2,
      "bounces_unique":2,
      "bounces_unique_hard":2,
      "bounces_unique_soft":0,
      "bounces_unique_other":0,
      "bounces_unique_local":0,
      "bounces_unique_remote":2,
      "clicks_total":22,
      "clicks_unique":22,
      "clicks_unique_by_link":22,
      "opens_total":299,
      "opens_unique":101,
      "scomps_total":2,
      "scomps_unique":2,
      "scomps_status_updated":2,
      "unsubs_total":30,
      "unsubs_unique":23,
      "unsubs_status_updated":0,
      "bounces_status_updated":0,
      "total_messages":0,
      "total_success":0,
      "total_failure":0,
      "total_failure_toolong":0,
      "bounces_unique_by_code":{
         "200":1,
         "209":1
      },
      "messages_sent":277,
      "messages_html":274,
      "messages_text":3,
      "accepted":275,
      "accepted_rate":0.9927797833935018,
      "in_queue":0,
      "in_queue_rate":0.0,
      "max_unique_activities":101,
      "open_rate":0.36727272727272725,
      "open_ratio":2.9603960396039604,
      "unopened":174,
      "duplicate_opens":198,
      "duplicate_clicks":0,
      "click_rate":0.08,
      "click_to_open_rate":0.21782178217821782,
      "unclicked":253,
      "bounced":2,
      "duplicate_bounces":0,
      "unbounced":275,
      "bounce_rate":0.007220216606498195,
      "bounce_rate_hard":1.0,
      "bounce_rate_soft":0.0,
      "bounce_rate_other":0.0,
      "bounce_local_rate":0.0,
      "duplicate_scomps":0,
      "duplicate_unsubs":7,
      "unsub_rate":0.08363636363636363,
      "skips_error":2,
      "skips_request":17
   },
   "error_code":null,
   "error_message":null
}