Subscribers API

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 https://app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/subscribers

Request Parameters

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.

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 Kasplo 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 https://app.kasplo.com/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@example.net",
          "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@example.net",
          "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 https://app.kasplo.com/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 Kasplo App.
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 https://app.kasplo.com/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: Kasplo-app.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 https://app.kasplo.com/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:

  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 https://app.kasplo.com/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: Kasplo-app.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",
            "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

Update an existing subscriber

URL

PUT https://app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/subscribers/:subscriber_id

Request Parameters

mailing_list_id

The mailing list to onto which to add the subscriber
subscriber_id

The id of the subscriber to update

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 https://app.kasplo.com/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: Kasplo-app.dev 
                              Accept: */*
                              content-type: application/json
                              Content-Length:
                            {
        "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. </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`.

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 https://app.kasplo.com/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 https://app.kasplo.com/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 https://app.kasplo.com/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@example.net",
        "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 https://app.kasplo.com/ga/api/v2/subscribers_by_email/:email

Search for subscribers on a specific mailing list:

GET https://app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/subscribers_by_email/:email

Search for subscribers in a specific organization:

GET https://app.kasplo.com/ga/api/v2/organizations/:organization_id/subscribers_by_email/:email

Search for subscribers in all organizations:

GET https://app.kasplo.com/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 https://app.kasplo.com/ga/api/v2/organizations/1/subscribers_by_email/user@example.com
    

HTTP/1.1 200 OK
    

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