Subscribers API

Table of Contents
Remote Lists
Get a list of subscribers
Get subscriber details
- URL
- Request Parameters
- Notes
- Response
- Example
Create a new subscriber
Update an existing subscriber
Trigger Autoresponders on a Subscriber
Unsubscribe
- URL
- Request Payload
- Response
- Example
Find subscribers with a given email address
Delete a Subscriber

Remote Lists

Subscribers 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 subscribers

Get the details for all subscribers on this list.

URL

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

GET /ga/api/v2/mailing_lists/:mailing_list_id/subscribers?segment_id=:segment_id

Request Parameters

mailing_list_id	The `id` of the mailing list to query.
segment_id	The `id` of the segment with which to filter the list of subscribers.

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.

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 GreenArrow 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": "[email protected]",
      "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": "[email protected]",
      "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

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
subscriber_ids_or_emails	A comma-separated list of up to `100` subscriber ids or URI encoded email addresses

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.

id
integer

The id of the subscriber

mailing_list_id
integer

The id of the mailing list

email
string

The subscriber’s email address

created_at
string

The date the subscriber record was added to GreenArrow Studio.

email_format
string

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

status
string

The status of the subscriber.

subscribe_time
string

The time the subscriber subscribed.

subscribe_ip
string

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

custom_fields
hash

The key for each entry is the name of the custom field. The value is a hash with the keys listed below.

name
string

The name of the custom field which this entry represents.

type
string

The type of the custom field.

Can be any of the following:

text
text_multiline
number
date
select_single_dropdown
select_single_radio
select_multiple_checkboxes
boolean

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

Example

> 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: greenarrow-studio.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": "[email protected]",
            "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": "[email protected]",
            "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

mailing_list_id
integer

The mailing list to onto which to add the subscriber

Request Payload

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

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 / optional	The time the subscriber subscribed. This defaults to the current time.
subscribe_ip string / optional	The IP the subscriber subscribed from. This may be `null` if it is unknown.
custom_fields hash / optional	A hash of custom field values. The keys of this hash should be the name of the custom field, and the values of this hash should be the new value of the custom field.
skip_autoresponders boolean / optional	Do not run autoresponders for this new subscriber (see 1 below). Currently this option does not apply when using `confirmation_form_id`. In future releases this limitation may be removed without notice, so do not rely on this behavior.
autoresponder_filter string / optional	Only run the autoresponders that match this case-insensitive string glob (see 4 below). Currently this option does not apply when using `confirmation_form_id`. In future releases this limitation may be removed without notice, so do not rely on this behavior.
autoresponder_exclude_reacted boolean / optional	Do not run autoresponders if this subscriber has a reaction in the queue (see 5 below). Currently this option does not apply when using `confirmation_form_id`. In future releases this limitation may be removed without notice, so do not rely on this behavior.

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.

apply_custom_field_defaults
boolean
/
default: false

If true, custom field default values will be applied to the new subscriber. By default, custom field default values are not applied to new subscribers.

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

The skip_autoresponders field must not be enabled.
The autoresponder must trigger on Subscription.
The autoresponder trigger must be configured with the Run From API? option enabled.
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.
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: greenarrow-studio.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": "[email protected]",
        "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": "[email protected]",
        "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

Update an existing subscriber

URL

Update a subscriber by subscriber id:

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

Update a subscriber by email address:

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

Request Parameters

mailing_list_id	The mailing list to onto which to add the subscriber
subscriber_id	The id of the subscriber to update. Only one of `subscriber_id` or `email_address` can be used
email_address	The email address of the subscriber to update. Only one of `subscriber_id` or `email_address` can be used

Request Payload

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

email string	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.
status string	The status of the subscriber.
subscribe_time string	The time the subscriber subscribed.
subscribe_ip string	The ip the subscriber subscribed from. This can be `null` if it is unknown.
custom_fields hash / optional	A hash of custom field values. The keys of this hash should be the name of the custom field, and the values of this hash should be the new value of the custom field.
run_autoresponders boolean	Run autoresponders on this subscriber as though it was just created. Defaults to `false`.

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.

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: greenarrow-studio.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": "[email protected]",
        "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": "[email protected]",
        "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, [email protected] 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. </p>

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.

</p> Only one of autoresponder_names and autoresponder_ids may be provided. </p>

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`.

In the content of the autoresponder, you may append :raw to the replacement code to cause GreenArrow to not perform HTML/URL encoding on the replaced value. For example, if your API call includes a URL component that is already encoded, you might provide it as url_ent and use it in your content as %%api:url_ent:raw%%.

Be careful when using raw content replacement fields. You are responsible for HTML entity encoding and/or URI encoding. Additionally, when a raw content replacement field is used in a link the resulting URL may depend on if click tracking is used with the email.

If click tracking is used, then the raw bytes of the content replacement field are inserted into the URL in the `Location` header returned to the client. The raw bytes never go through a HTML context, and thus any HTML entities present (for example `&`) will not be decoded.

If click tracking is not used, the raw bytes of the content replacement field are inserted into the HTML href attribute. The browser will interpret any HTML entities present. Additionally, if the href attribute value is enclosed in double or single quotation marks, a non-HTML-entity-escaped double or single quotation mark can prematurely end the href attribute value.

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": "[email protected]",
      "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

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.

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": "[email protected]",
    "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
}

Find subscribers with a given email address

Find the list of subscribers in this organization that have the specified email address.

URL

Search for subscribers on all mailing lists in the authenticated API key’s organization:

GET /ga/api/v2/subscribers_by_email/:email

Search for subscribers on a specific mailing list:

GET /ga/api/v2/mailing_lists/:mailing_list_id/subscribers_by_email/:email

Search for subscribers in a specific organization:

GET /ga/api/v2/organizations/:organization_id/subscribers_by_email/:email

Search for subscribers in all organizations:

GET /ga/api/v2/organizations/all/subscribers_by_email/:email

Request Parameters

organization_id integer	The specific organization to query. Set to `all` to search all organizations. This may only be used by system administrators.
email string	The email address to search for within the given scope. This value should be URI encoded.
mailing_list_id integer	The mailing list ID to limit the subscribers that will be returned.

Response

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

id
integer

The id of the subscriber

status
string

The current status of this subscriber.

Will be one of: active, bounced, unsubscribed, scomp, deactivated

mailing_list
hash

id integer	The `id` of the mailing list on which this subscriber was found.
name string	The `name` of the mailing list on which this subscriber was found.

organization
hash

This key is only present if all_organizations is true.

id integer	The `id` of the organization on which this subscriber was found.
name string	The `name` of the organization on which this subscriber was found.

Example

GET /ga/api/v2/organizations/1/subscribers_by_email/[email protected]

HTTP/1.1 200 OK

{
  "success": true,
  "error_code": null,
  "error_message": null,
  "per_page": 100,
  "page": 0,
  "data": [
    {
      "id": 14,
      "status": "active",
      "email": "[email protected]",
      "mailing_list": {
        "id": 14,
        "name": "Mailing List #14"
      }
    },
    {
      "id": 15,
      "status": "active",
      "email": "[email protected]",
      "mailing_list": {
        "id": 15,
        "name": "Mailing List #15"
      }
    },
    {
      "id": 16,
      "status": "active",
      "email": "[email protected]",
      "mailing_list": {
        "id": 16,
        "name": "Mailing List #16"
      }
    },
    {
      "id": 17,
      "status": "active",
      "email": "[email protected]",
      "mailing_list": {
        "id": 17,
        "name": "Mailing List #17"
      }
    }
  ],
  "next_page_token": null,
  "num_records": 4,
  "num_pages": 1
}

Delete a Subscriber

Delete a subscriber from Studio’s database.

Subscribers can be deleted, but we don’t recommend this for general use. Typically, you should prefer to unsubscribe or deactivate subscribers instead of deleting them. This helps you to ensure that they don’t inadvertently rejoin your list after being removed.

However, if you need to delete subscribers for GDPR or other privacy law reasons, this is supported by GreenArrow.

In order to delete subscriber records, the configuration directive studio_disable_subscriber_deletion must not be enabled.

URL

DELETE /ga/api/v2/mailing_lists/:mailing_list_id/subscribers/:id_or_email

Request Parameters

mailing_list_id integer	The mailing list ID from which the subscriber is to be deleted.
id_or_email string	Either the subscriber ID or the subscriber’s email address to be deleted.

Response

The response will be a JSON object containing the following keys.

subscriber_ids_removed
array of integers

The list of subscriber IDs that were deleted as a result of this API call.

more_remaining
boolean

Whether or not there are additional subscribers that could have been deleted that weren’t by this API call. The primary cause of this would be if (1) the mailing list has an alternate primary key, (2) you’re attempting to delete subscribers by email address, and (3) more than 10 subscriber records use that email address. Given that this is quite an edge case, in the vast majority of cases more_remaining will be false.

Example

DELETE /ga/api/v2/mailing_lists/184/subscribers/510

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "subscriber_ids_removed": [
      510
    ],
    "more_remaining": false
  },
  "error_code": null,
  "error_message": null
}

Example (Feature disabled)

DELETE /ga/api/v2/mailing_lists/188/subscribers/514

HTTP/1.1 200 OK

{
  "success": false,
  "data": null,
  "error_code": "validation_failed",
  "error_message": "Subscriber id=514 could not be deleted: Subscriber deletion is disabled by the configuration directive studio_disable_subscriber_deletion."
}