Subscribers API¶

Get a list of subscribers¶

Get the details for all subscribers on this list.

URL¶

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

Request Parameters¶

Key	Meaning
mailing_list_id	The id of the mailing list to query.

Pagination¶

This endpoint returns its records paginated. The subscriber records will be sorted by their id in ascending order.

Querying without any additional parameters will return the first page. The following extra parameters may be specified.

Key	Meaning
page	The page number to retrieve (starts at 0).
page_token	The page token to retrieve. This is explained below.
per_page	The number of records to return per page (default 100, maximum 500).

There are two ways to page through the data:

• Sequentially increment page to specify additional page numbers until you have retrieved every page of the results. When subscribers are added or removed the page boundaries may shift, and it's possible that some subscribers will be missed between pages or returned on two adjacent pages.

• Provide in page_token the next_page_token value returned by the most recent call to this API which got the previous page. This guarantees that the next returned page will start immediately after the previous page, with all pages being contiguous and non-overlapping. When a next_page_token of null is returned, that indicates that this is the last page.

If you are presenting a list of pages to the user, you probably want to use page. If you want to retrieve all of the data, page_token is likely what you want. (When retrieving all data, the page_token method allows InboxFirst to more efficiently provide the data.)

Both page and page_token may not be specified in the same request.

Response¶

The response will be an array of subscriber hashes, the same as returned by the Get subscriber details endpoint documented below.

Example¶

> GET /ga/api/v2/mailing_lists/1/subscribers?per_page=2 HTTP/1.1
> Authorization: Basic MTpkOTgzOGM4MDBlMmY3ODAxMWY0MTc1NWUzMGIwY2QzNWJiYTA1ZDYx
> Accept: application/json
> Content-Type: application/json

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "9394b6420de28ae7f15744c4a7aa9681"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=67423ec44938ad4beb4de1f8e9c684a0; path=/; HttpOnly
< X-Request-Id: 12cc0a5d90bbc75779478a30e8793e6b
< X-Runtime: 0.077669
< Connection: close
< Server: thin 1.5.0 codename Knife

{
  "success": true,
  "error_code": null,
  "error_message": null,
  "per_page": 2,
  "page": 0,
  "data": [
    {
      "id": 1,
      "mailing_list_id": 1,
      "email": "user-1@discardallmail.inboxfirst.com",
      "created_at": "2015-03-09T10:34:04-05:00",
      "created_at_epoch": 1425915244,
      "status": "active",
      "subscribe_time": "2015-03-09T10:34:04-05:00",
      "subscribe_time_epoch": 1425915244,
      "subscribe_ip": null,
      "custom_fields": {
        "new field 1": {
          "name": "new field 1",
          "type": "text",
          "value": null
        },
        "new field 2": {
          "name": "new field 2",
          "type": "text",
          "value": null
        }
      }
    },
    {
      "id": 2,
      "mailing_list_id": 1,
      "email": "user-2@discardallmail.inboxfirst.com",
      "created_at": "2015-03-09T10:36:55-05:00",
      "created_at_epoch": 1425915415,
      "status": "active",
      "subscribe_time": "2015-03-09T10:36:55-05:00",
      "subscribe_time_epoch": 1425915415,
      "subscribe_ip": "10.0.81.5",
      "custom_fields": {
        "new field 1": {
          "name": "new field 1",
          "type": "text",
          "value": null
        },
        "new field 2": {
          "name": "new field 2",
          "type": "text",
          "value": null
        }
      }
    }
  ],
  "next_page_token": "EDZmZjYkFGOjlzM"
}

Get subscriber details¶

Get the details for up to 100 subscribers at a time.

URL¶

GET /ga/api/v2/mailing_lists/:mailing_list_id/subscribers/:subscriber_ids_or_emails

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
subscriber_ids_or_emails	A comma-separated list of up to 100 subscriber ids or URI encoded email addresses	1,9182,bob%40example.com,9981

Notes¶

• The email addresses in the request should be URI encoded.

• If the request includes an email address used by multiple subscribers on the mailing list (as might be the case if the mailing list uses an alternate primary key), the API will return all subscribers with that email address.

Response¶

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

Key	Meaning	Example	Type
id	The id of the subscriber	123	Integer
mailing_list_id	The id of the mailing list	456	Integer
email	The subscriber's email address	bob@example.com	String
created_at	The date the subscriber record was added to InboxFirst.	2013-03-27T10:14:13-05:00	String
email_format	The subscriber's email format. This column is only presented for mailing lists which use the Format field.	plaintext or html	String
status	The status of the subscriber.	active, bounced, unsubscribed, scomp or deactivated	String
subscribe_time	The time the subscriber subscribed.	2013-03-27T10:14:13-05:00	String
subscribe_ip	The IP the subscriber subscribed from. This can be null if it is unknown.	192.168.0.123	String
custom_fields	An array of entries matching the definition found below.		Hash

Each entry in the custom_fields hash are keyed for the name of the custom field, and the value being a hash containing the following keys.

Key	Meaning	Example	Type	Present for Custom Field Types
name	The name of the custom field which this entry represents.	First Name	String	All
type	The type of the custom field.	text, text_multiline, number, date, select_single_dropdown, select_single_radio, select_multiple_checkboxes, boolean	String	All
value	The string value of the custom field.	James McGuy	String	text, text_multiline, select_single_dropdown, select_single_radio
value	The integer value of the custom field.	9182	Integer	number
value	The boolean value of the custom field.	true or false	Boolean	boolean
value	The date value of the custom field.	2000-02-17	String	date
value	The list of values selected for the custom field.		Array of strings	select_multiple_checkboxes

Example Request¶

> GET /ga/api/v2/mailing_lists/1/subscribers/1,2 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
< Content-Type: text/html
< X-UA-Compatible: IE=Edge
< ETag: "68a7c81054bbf60f3b6ee5c481e5245b"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=ef4d24b30d8700118859eb7a8d0d291c; path=/; HttpOnly
< X-Request-Id: 3a5478ebf7c8d5bc047c8d989403c863
< X-Runtime: 0.028557
< Connection: close

{
    "data": [
        {
            "created_at": "2013-01-31T14:25:48-06:00",
            "custom_fields": {
                "First Name": {
                    "name": "First Name",
                    "type": "text",
                    "value": "Bob"
                },
                "boolean test": {
                    "name": "boolean test",
                    "type": "boolean",
                    "value": false
                },
                "boolean test yes by default": {
                    "name": "boolean test yes by default",
                    "type": "boolean",
                    "value": true
                },
                "radio test": {
                    "name": "radio test",
                    "type": "select_single_radio",
                    "value": "bar"
                }
            },
            "email": "bob@example.com",
            "id": 1,
            "mailing_list_id": 1,
            "status": "active",
            "subscribe_ip": null,
            "subscribe_time": "2013-01-31T14:25:48-06:00"
        },
        {
            "created_at": "2013-01-31T14:25:48-06:00",
            "custom_fields": {},
            "email": "joe@example.net",
            "id": 2,
            "mailing_list_id": 1,
            "status": "active",
            "subscribe_ip": null,
            "subscribe_time": "2013-01-31T14:25:48-06:00"
        }
    ],
    "error_code": null,
    "error_message": null,
    "success": true
}

Create a new subscriber¶

URL¶

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

Request Parameters¶

Key	Meaning	Example
mailing_list_id	The mailing list to onto which to add the subscriber	99182

Request Payload¶

The POST request should have a JSON document in its payload with all of the following keys.

{apitable}

subscriber (hash):

    email (string; required):

        The subscriber's email address.

    email_format (string):

        The subscriber's email format. This column is only needed for mailing lists which use the Format field.

        - Must be one of: `plaintext`, `html`

    status (string; required):

        The status of the subscriber.

        - Must be one of: `active`, `bounced`, `unsubscribed`, `scomp`, `deactivated`

    subscribe_time (string; required):

        The time the subscriber subscribed.

    subscribe_ip (string; optional):

        The IP the subscriber subscribed from. This may be `null` if it is unknown.

    custom_fields (array of hashes; optional):

        An array of entries matching the definition found below, each hash representing the value of a custom field.

        name (string):

            The name of the custom field which this entry represents.

        value (type varies):

            - Should be a string if the type is: `text`, `text_multiline`, `select_single_dropdown`, `select_single_radio`
            - Should be an integer if the custom field type is: `number`
            - Should be a boolean if the custom field type is: `boolean`
            - Should be a date string in the format `YYYY-MM-DD` if the custom field type is: `date`
            - Should be an array of selected values if the custom field type is: `select_multiple_checkboxes`

    skip_autoresponders (boolean; optional):

        Do not run autoresponders for this new subscriber (see 1 below).

        - This option does not apply when using `confirmation_form_id`.

    autoresponder_filter (string; required):

        Only run the autoresponders that match this case-insensitive string glob (see 4 below).

        - This option does not apply when using `confirmation_form_id`.

    autoresponder_exclude_reacted (boolean; required):

        Do not run autoresponders if this subscriber has a reaction in the queue (see 5 below).

        - This option does not apply when using `confirmation_form_id`.

confirmation_form_id (integer):

    If provided, this user will not be immediately added.  Instead, the
    user will be sent a confirmation email. Only after clicking the
    link provided in the confirmation email will the user be added to
    the mailing list.

    If the new subscriber's status is not `active`, the confirmation email
    will not be sent and the subscriber will be immediately added to the
    list in whatever non-active status was specified.

    - If the user's organization has `Require Confirmed Opt-In` enabled, then this is a required field.
    - The selected form must require confirmation.
    - The form must be a Subscription form.

{/apitable}

In order for an autoresponder to be triggered for later sending, the following must be true:

1. The skip_autoresponders field must not be enabled.
2. The autoresponder must trigger on Subscription.
3. The autoresponder trigger must be configured with the Run From API? option enabled.
4. If specified, the autoresponder_filter field will reduce the list of autoresponders that are run to those whose name matches the glob, where * is a wildcard character.
5. If specified, the autoresponder_exclude_reacted field will cause all autoresponders to be skipped if any autoresponder remaining at this point contains a reaction in the queue for this subscriber. This only evaluates autoresponders that: (a) are configured with Run from API? as true (step 3), (b) match the pattern provided in autoresponder_filter if present (step 4), and (c) are paused or un-paused.

Response¶

A successful response will return the subscriber record using the format described in the "Get subscriber details" section of the API.

A failure will return a standard error response with an explanation of what went wrong.

Example¶

> POST /ga/api/v2/mailing_lists/4/subscribers 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: */*
> Content-Length: 430
> Content-Type: application/json

{
    "subscriber": {
        "custom_fields": {
            "First Name": "Ted",
            "boolean test": false,
            "boolean test yes by default": true,
            "radio test": "bar"
        },
        "email": "ted@example.com",
        "mailing_list_id": 4,
        "status": "active",
        "subscribe_ip": null,
        "subscribe_time": "2013-02-01T08:22:42-06:00"
    }
}

< HTTP/1.1 200 OK
< Content-Type: text/html
< X-UA-Compatible: IE=Edge
< ETag: "e5794f737673a63d76a5741a66332d22"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=d27440cb5fba4c7a579920acd8986636; path=/; HttpOnly
< X-Request-Id: 293ca6db3ed520f5be284686cfc7b7ed
< X-Runtime: 0.046717
< Connection: close

{
    "data": {
        "created_at": "2013-03-29T13:27:50-05:00",
        "custom_fields": {
            "First Name": {
                "name": "First Name",
                "type": "text",
                "value": "Ted"
            },
            "boolean test": {
                "name": "boolean test",
                "type": "boolean",
                "value": false
            },
            "boolean test yes by default": {
                "name": "boolean test yes by default",
                "type": "boolean",
                "value": true
            },
            "radio test": {
                "name": "radio test",
                "type": "select_single_radio",
                "value": "bar"
            }
        },
        "email": "ted@example.com",
        "id": 3386566,
        "mailing_list_id": 4,
        "status": "active",
        "subscribe_ip": null,
        "subscribe_time": "2013-02-01T08:22:42-06:00"
    },
    "error_code": null,
    "error_message": null,
    "success": true
}

Example code¶

• Create a new subscriber
• Create a new subscriber with custom fields

Update an existing subscriber¶

URL¶

PUT /ga/api/v2/mailing_lists/:mailing_list_id/subscribers/:subscriber_id

Request Parameters¶

Key	Meaning	Example
mailing_list_id	The mailing list to onto which to add the subscriber	99182
subscriber_id	The id of the subscriber to update	17293 or bob@example.com (URI encoded as bob%40example%2Ecom)

Request Payload¶

The PUT request should have a JSON document in its payload with all of the following keys.

Key	Meaning	Example	Type
subscriber.email	The subscriber's email address	bob@example.com	String
subscriber.email_format	The subscriber's email format. This column is only needed for mailing lists which use the Format field.	plaintext or html	String
subscriber.status	The status of the subscriber.	active, bounced, unsubscribed, scomp or deactivated	String
subscriber.subscribe_time	The time the subscriber subscribed.	2013-03-27T10:14:13-05:00	String
subscriber.subscribe_ip	The ip the subscriber subscribed from. This can be null if it is unknown.	192.168.0.123	String
subscriber.custom_fields	An array of entries matching the definition found below.		Hash
subscriber.run_autoresponders	Run autoresponders on this subscriber as though it was just created. Defaults to false.	true	Boolean

• The run_autoresponders option does not affect reactions that are already in the queue. Using this parameter, it is possible for an autoresponder to be sent to the same subscriber multiple times.

Each entry in the specified custom_fields hash must have the following keys. The keys for the hash is the name of the custom field.

Key	Meaning	Example	Type	Present for Custom Field Types
name	The name of the custom field which this entry represents.	First Name"	String	All
value	The string value of the custom field.	James McGuy	String	text, text_multiline, select_single_dropdown, select_single_radio
value	The integer value of the custom field.	9182	Integer	number
value	The boolean value of the custom field.	true or false	Boolean	boolean
value	The date value of the custom field.	2000-02-17	String	date
value	The list of values selected for the custom field.		Array of strings	select_multiple_checkboxes

Response¶

A successful response will return the subscriber record using the format described in the "Get subscriber details" section of the API.

A failure will return a standard error response with an explanation of what went wrong.

Example¶

> PUT /ga/api/v2/mailing_lists/4/subscribers/10012 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: */*
> content-type: application/json
> Content-Length: 343

{
    "subscriber": {
        "custom_fields": {
            "First Name": "bobbie",
            "boolean test": false,
            "boolean test yes by default": true,
            "radio test": "bar"
        },
        "email": "renamed@example.com",
        "status": "active",
        "subscribe_ip": null,
        "subscribe_time": "2013-02-01T08:22:42-06:00"
    }
}

< HTTP/1.1 200 OK
< Content-Type: text/html
< X-UA-Compatible: IE=Edge
< ETag: "2b2badce6c43e80e30a9d85aea2c9dff"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=68685553f5c70ce29e9b03929e5201b0; path=/; HttpOnly
< X-Request-Id: bdce4f074d21a3a3c8ccfca067852cdd
< X-Runtime: 0.024645
< Connection: close
<
* Closing connection #0

{
    "data": {
        "created_at": "2013-02-01T08:22:42-06:00",
        "custom_fields": {
            "First Name": {
                "name": "First Name",
                "type": "text",
                "value": "bobbie"
            },
            "boolean test": {
                "name": "boolean test",
                "type": "boolean",
                "value": false
            },
            "boolean test yes by default": {
                "name": "boolean test yes by default",
                "type": "boolean",
                "value": true
            },
            "radio test": {
                "name": "radio test",
                "type": "select_single_radio",
                "value": "bar"
            }
        },
        "email": "renamed@example.com",
        "id": 10012,
        "mailing_list_id": 4,
        "status": "active",
        "subscribe_ip": null,
        "subscribe_time": "2013-02-01T08:22:42-06:00"
    },
    "error_code": null,
    "error_message": null,
    "success": true
}

Example code¶

• Update an existing subscriber

Trigger Autoresponders on a Subscriber¶

This endpoint will trigger autoresponders for a single subscriber. The list of autoresponders to trigger may be provided by name or by ID.

Any autoresponder(s) may be triggered using this endpoint - it is not restricted to just autoresponders configured to use an "API" trigger.

If any error is returned by this method, no autoresponders will be triggered.

URL¶

POST /ga/api/v2/mailing_lists/:mailing_list_id/subscribers/:subscriber_id_or_email/trigger_autoresponders

Request Parameters¶

In the URL of the request, the following values must be replaced.

mailing_list_id integer	The ID of the mailing list that contains the subscriber record.
subscriber_id_or_email string	This may either be the numeric ID for the subscriber record, or an email address. If this value is an email address, it must be URI escaped. For example, bob@example.com escapes as bob%40example.com.

Request Payload¶

The body of this request should be a JSON hash with the following keys.

create_missing_subscriber boolean — default false	Studio can only send autoresponders to subscribers that are on the mailing list. If the subscriber is not found on the mailing list and this flag is true, the subscriber will be added to the mailing list. subscriber_id_or_email must be an email address for this to work. If it is an integer and not found on the list a not_found error will be returned. If it is an improperly formatted email address a validation_failed error will be returned. If if the custom field data for the subscriber does not pass validation a validation_failed error will be returned. NOTE: On-subscription autoresponders that are configured to respond to subscribers created on the API will be triggered on subscribers created due to this flag. This can be prevented with the skip_subscription_autoresponders option. WARNING: If you are also using this mailing list to send campaigns, you need to make sure you're not implicitly subscribing people to get mailing list messages from you, if that's not what you want.
reactivate_subscriber boolean — default false	Studio can only send autoresponders to subscribers that have a status of active. If the requested subscriber exists on the mailing list and is in a non-active status: If this flag is true: the subscriber will be reactivated (its status set back to active) and the autoresponder will be triggered. If this flag is false: an invalid_request error will be returned. WARNING: If you are also using this mailing list to send campaigns, be careful with this flag! This will reactivate the subscriber, potentially causing them to receive campaigns from which they had previously unsubscribed.
skip_subscription_autoresponders boolean — default false	Set this value to true to skip subscription autoresponders that would have triggered as a result of a new subscriber being created with the create_missing_subscriber flag.
autoresponder_names array of strings	The list of autoresponders, by name, that should be triggered. The asterisk (*) is used as a wildcard character — if you have autoresponders named AR 1 and AR Two, then including AR * in autoresponder_names will cause both to be triggered. Only one of autoresponder_names and autoresponder_ids may be provided.
autoresponder_ids array of integers	The list of autoresponders, by numeric ID, that should be triggered. Only one of autoresponder_names and autoresponder_ids may be provided.
content_replacement_fields hash of strings to strings	If provided, the key/value pairs in this hash will be interpolated into the content of the autoresponder, prefixed with an api: string with whitespace replaced as underscores. For example, if you provide the hash { "my_value": "Hello World", "Second Key": "Here's another value" }, anywhere in your autoresponder content that contains %%api:my_value%% or %%api:Second_Key%% will be replaced with Hello World and Here's another value, respectively. Spaces in the key must be replaced with underscores when entering the replacement code into your Autoresponder's content. These values are only used for interpolation into the email(s) generated by this API request. Any subsequent autoresponders or campaigns sent to this subscriber will have no knowledge or history of these content_replacement_fields values. These values are not passed to Special Sending Rules. Fields present in this hash will override Custom Field counterparts with the same name. If you include a `content_replacement_fields` key `First Name`, it will override any custom field named `API:First Name`. The hash keys are validated as follows: Keys must not be blank Keys must not consist of only whitespace Keys must contain at least one alphanumeric character A-Z a-z 0-9 Keys must be case-insensitive unique Keys must be 50 characters or less Whitespace within keys are treated as underscores - so First_Name and First Name are the same key If a key is passed that does not match this, an `invalid_request` error will be returned.
custom_fields hash Each value in this hash contains custom field data to be applied to the subscriber record. These hashes should be like { "Custom Field Name": "My Value" } -- just as though it was being passed to update a subscriber record. By default, if the subscriber is not active, this update will be not be applied. If reactivate_subscriber is set to true, then the subscriber will be reactivated and these updates will be applied. The more specific hashes take precedence over the for_all hash. For example, if you pass in a First Name key in both for_all and for_new -- the value in for_new will be set. However, if both hashes contain unique keys - then all of the values will be set. If the provided (or if a custom field is required, and not provided) custom fields result in a validation error on the subscriber record, no autoresponder will be sent. A validation error will be returned. for_all hash This is the base custom field data. Values in this hash will be applied to any subscriber that is successfully triggered. for_new hash This custom field data will be applied to subscribers that are created as a result of create_missing_subscriber being set to true and the subscriber not already existing in the mailing list. for_active hash This custom field data will be applied to subscribers who already existed and are active on the mailing list. for_reactivated hash This custom field data will be applied to subscribers who are reactivated as a result of reactivate_subscriber being set to true.

Response¶

A successful response will contain the following keys.

triggered_autoresponders array of hashes id integer The ID of the autoresponder that was triggered. name string The name of the autoresponder that was triggered.
subscriber hash	The subscriber record that was used for this call, as described in the format described in the "Get subscriber details" section of this API. The record that is returned will be after any updates in this request have been applied.
subscription_result string	The result of the subscript as a result of this API call. If the subscriber was created, this value will be created. If the subscriber already existed and was active, this value will be remained_active. If the subscriber already existed and was reactivated, this value will be reactivated. If none of those situations applied, this call should have already resulted in an error.

Example¶

> POST /ga/api/v2/mailing_lists/2/subscribers/bob%40example.com/trigger_autoresponders HTTP/1.1
> Authorization: Basic MToyYjBmNTA5YjQ3MDk1ODk0Mzk5ZWRkMGVhODE1ZDlkMjQ4MzUwYjc4
> Accept: application/json
> Content-Type: application/json

{
  "autoresponder_ids": [
    203
  ],
  "custom_fields": {
    "for_new": {
      "First Name": "Bob",
      "Last Name": "Example"
    }
  },
  "create_missing_subscriber": true
}

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "29694bdf4c95e5a20de5d440073eff40"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=f6f0a9eac82fc88c3bbb036e0ac74390; path=/; HttpOnly
< X-Request-Id: a62aeb23d79348c61ddecaffaf231575
< X-Runtime: 0.183498
< Connection: close
< Server: thin

{
  "success": true,
  "data": {
    "triggered_autoresponders": [
      {
        "id": 203,
        "name": "by api"
      }
    ],
    "subscriber": {
      "id": 3430120,
      "mailing_list_id": 2,
      "email": "bob@example.com",
      "created_at": "2015-09-29T14:07:34-05:00",
      "created_at_epoch": 1443553654,
      "status": "active",
      "subscribe_time": "2015-09-29T14:07:34-05:00",
      "subscribe_time_epoch": 1443553654,
      "subscribe_ip": null,
      "custom_fields": {
        "First Name": {
          "name": "First Name",
          "type": "text",
          "value": "Bob"
        },
        "Last Name": {
          "name": "Last Name",
          "type": "text",
          "value": "Example"
        }
      }
    },
    "subscription_result": "created"
  },
  "error_code": null,
  "error_message": null
}

Unsubscribe¶

Unsubscribe a subscriber using a token from the delivered email. This will cause the unsubscribe event to be associated with the specific campaign/content in which the token was delivered.

The token which should be sent to this endpoint may be generated in the campaign content by including the replacement code %%unsubscribe_token%%.

URL¶

POST /ga/api/v2/subscribers/unsubscribe

Request Payload¶

{::nomarkdown}

unsubscribe hash token string The value for this field is obtained from the %%unsubscribe_token%% replacement code when composing a campaign's contents. It may then be used to generate a real unsubscribe on that campaign for this subscriber. ip string (optional) The IP address to use when logging this unsubscribe event. If this is not present, no IP will be set on the unsubscribe event.

{:/nomarkdown}

Response¶

A successful response will return the subscriber record using the format described in the "Get subscriber details" section of the API.

A failure will return a standard error response with an explanation of what went wrong.

Example¶

> POST /ga/api/v2/subscribers/unsubscribe HTTP/1.1
> Authorization: Basic MTpiYTVhZjYzN2JhYjA0NzM0ZjMyMDUwMTBkZWQyZjA3NGMzYmU2YTM1
> Accept: application/json
> Content-Type: application/json

{
  "unsubscribe": {
    "token": "0E2MiJGZlV2Y10iY4gTZhJWO3QTYyETM2EWLy0SMtETLx0iM",
    "ip": "127.0.0.7"
  }
}

< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "4778db54a2512804124ea70383ffa61c"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=044b98a3732095dd7bedcd96497215da; path=/; HttpOnly
< X-Request-Id: d3c93e6c84f61186f733dbbb3c354265
< X-Runtime: 0.105547
< Connection: close
< Server: thin 1.5.0 codename Knife

{
  "success": true,
  "data": {
    "id": 1,
    "mailing_list_id": 1,
    "email": "user-1@discardallmail.inboxfirst.com",
    "created_at": "2015-06-19T14:19:12-05:00",
    "created_at_epoch": 1434741552,
    "status": "unsubscribed",
    "subscribe_time": "2015-06-19T14:19:12-05:00",
    "subscribe_time_epoch": 1434741552,
    "subscribe_ip": null,
    "custom_fields": {
      "First Name": {
        "name": "First Name",
        "type": "text",
        "value": "Bob the Builder"
      }
    }
  },
  "error_code": null,
  "error_message": null
}