Custom email events

Airship delivers email messages through a provider (SparkPost). Custom email events represent events that occur at the provider level — outside Airship, between the provider and recipient.

Email bounce event

Occurs when an email could not be delivered to an address. The bounce_class provides additional information about the reason your message bounced. This event occurs in conjunction with a similar COMPLIANCE event.

Jump to examples ↓

OBJECT PROPERTIES

body objectREQUIRED
OBJECT PROPERTIES
- name stringREQUIRED
  Possible values: bounce
- properties objectREQUIRED
  All of
  - OBJECT PROPERTIES
    - email string
      The recipient’s email address.
    - sender string
      The sender of the email specified by the event.
    - subject string
      The subject line of the email specified by the event.
  - OBJECT PROPERTIES
    - bounce_class string
      A number between 1 and 100 that represents the specific reason the email bounced.
    - bounce_event_type string
      Possible values: bounce
- session_id string
  Represents the “session” of user activity. Absent if the application was initialized while backgrounded.
- source stringREQUIRED
  Possible values: API
- triggering_push object<Associated push>REQUIRED
  The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.
  An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.
device objectREQUIRED
Holds information about the email device (an individual email channel) the event occurred against.
OBJECT PROPERTIES
- channel string
  The unique, platform-agnostic channel identifier for a device.
- delivery_address stringREQUIRED
  The email address of the channel the event occurred against.
- device_type stringREQUIRED
  Email compliance events use the EMAIL device type.
  Possible values: EMAIL
- named_user string
  The Named User that the channel is associated with; appears only if the channel is associated with a Named User.

Used in:

Open an event stream

Examples

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@example.com"
  },
  "body": {
      "name": "bounce",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
        "sender": "baseball@example.com",
        "subject": "Baseball Season is Almost Here!",
        "email": "new.subscriber@example.com",
        "bounce_event_type": "bounce",
        "bounce_class": "10",
      }
  },
  "type": "CUSTOM"
}

Email click event

Occurs when a recipient clicks a tracked link in a message. Tracked links are redirected through the provider’s click-tracking server to record the event. Only HTTP and HTTPS links are tracked. Unsubscribe link clicks do not trigger this event.

Jump to examples ↓

OBJECT PROPERTIES

body objectREQUIRED
OBJECT PROPERTIES
- name stringREQUIRED
  Possible values: click
- properties objectREQUIRED
  All of
  - OBJECT PROPERTIES
    - email string
      The recipient’s email address.
    - sender string
      The sender of the email specified by the event.
    - subject string
      The subject line of the email specified by the event.
  - OBJECT PROPERTIES
    - link_name string
      The name of the link, if set.
    - link_url string
      The URL of the link that the user clicked.
  - OBJECT PROPERTIES
    - agent_family string
      The name of the family of user agent software used to access the email, e.g., WebKit
    - device_brand string
      The brand of the device that was used to access the user agent software, e.g., Samsung or Apple.
    - device_family string
      The name of the device used to access the user agent software.
    - is_mobile boolean
      Indicates whether or not the user agent is from a mobile device.
    - is_prefetched boolean
      Indicates if this event was likely prefetched, for example through Apple MPP. This field does not apply to clicks. The value returned in click events is always false.
    - os_family string
      The name of the operating system used to access the user agent software.
    - os_version string
      The version of the operating system used to access the user agent software.
- session_id string
  Represents the “session” of user activity. Absent if the application was initialized while backgrounded.
- source stringREQUIRED
  Possible values: API
- triggering_push object<Associated push>REQUIRED
  The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.
  An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.
device objectREQUIRED
Holds information about the email device (an individual email channel) the event occurred against.
OBJECT PROPERTIES
- channel string
  The unique, platform-agnostic channel identifier for a device.
- delivery_address stringREQUIRED
  The email address of the channel the event occurred against.
- device_type stringREQUIRED
  Email compliance events use the EMAIL device type.
  Possible values: EMAIL
- named_user string
  The Named User that the channel is associated with; appears only if the channel is associated with a Named User.

Used in:

Open an event stream

Examples

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@example.com"
  },
  "body": {
      "name": "click",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@example.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "new.subscriber@example.com",
          "link_name": "Homepage",
          "link_url": "https://www.example.com",
          "os_family": "Android",
          "is_mobile": "true",
          "device_brand": "Motorola",
          "os_version": "11",
          "device_family": "moto g stylus",
          "is_prefetched": "false",
          "agent_family": "Chrome"
      }
  },
  "type": "CUSTOM"
}

Email delay event

Occurs when a mailbox provider temporarily rejects an email. In general, this event indicates that the provider will attempt to resend the message.

Jump to examples ↓

OBJECT PROPERTIES

body objectREQUIRED
OBJECT PROPERTIES
- name stringREQUIRED
  Possible values: delay
- properties objectREQUIRED
  OBJECT PROPERTIES
  - email string
    The recipient’s email address.
  - sender string
    The sender of the email specified by the event.
  - subject string
    The subject line of the email specified by the event.
- session_id string
  Represents the “session” of user activity. Absent if the application was initialized while backgrounded.
- source stringREQUIRED
  Possible values: API
- triggering_push object<Associated push>REQUIRED
  The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.
  An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.
device objectREQUIRED
Holds information about the email device (an individual email channel) the event occurred against.
OBJECT PROPERTIES
- channel string
  The unique, platform-agnostic channel identifier for a device.
- delivery_address stringREQUIRED
  The email address of the channel the event occurred against.
- device_type stringREQUIRED
  Email compliance events use the EMAIL device type.
  Possible values: EMAIL
- named_user string
  The Named User that the channel is associated with; appears only if the channel is associated with a Named User.

Used in:

Open an event stream

Examples

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "addressResponding4xx@example.com"
  },
  "body": {
      "name": "delay",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@example.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "addressResponding4xx@example.com"
      }
  },
  "type": "CUSTOM"
}

Email delivery event

Occurs when the remote MTA (email server) acknowledges receipt of a message.

Jump to examples ↓

OBJECT PROPERTIES

body objectREQUIRED
OBJECT PROPERTIES
- name stringREQUIRED
  Possible values: delivery
- properties objectREQUIRED
  OBJECT PROPERTIES
  - email string
    The recipient’s email address.
  - sender string
    The sender of the email specified by the event.
  - subject string
    The subject line of the email specified by the event.
- session_id string
  Represents the “session” of user activity. Absent if the application was initialized while backgrounded.
- source stringREQUIRED
  Possible values: API
- triggering_push object<Associated push>REQUIRED
  The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.
  An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.
device objectREQUIRED
Holds information about the email device (an individual email channel) the event occurred against.
OBJECT PROPERTIES
- channel string
  The unique, platform-agnostic channel identifier for a device.
- delivery_address stringREQUIRED
  The email address of the channel the event occurred against.
- device_type stringREQUIRED
  Email compliance events use the EMAIL device type.
  Possible values: EMAIL
- named_user string
  The Named User that the channel is associated with; appears only if the channel is associated with a Named User.

Used in:

Open an event stream

Examples

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@example.com"
  },
  "body": {
      "name": "delivery",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@example.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "new.subscriber@example.com"
      }
  },
  "type": "CUSTOM"
}

Email initial open event

Occurs when a recipient opens an email, rendering a tracking pixel at the top of the email.

Jump to examples ↓

OBJECT PROPERTIES

body objectREQUIRED
OBJECT PROPERTIES
- name stringREQUIRED
  Possible values: initial_open
- properties objectREQUIRED
  All of
  - OBJECT PROPERTIES
    - email string
      The recipient’s email address.
    - sender string
      The sender of the email specified by the event.
    - subject string
      The subject line of the email specified by the event.
  - OBJECT PROPERTIES
    - agent_family string
      The name of the family of user agent software used to access the email, e.g., WebKit
    - device_brand string
      The brand of the device that was used to access the user agent software, e.g., Samsung or Apple.
    - device_family string
      The name of the device used to access the user agent software.
    - is_mobile boolean
      Indicates whether or not the user agent is from a mobile device.
    - is_prefetched boolean
      Indicates if this event was likely prefetched, for example through Apple MPP. This field does not apply to clicks. The value returned in click events is always false.
    - os_family string
      The name of the operating system used to access the user agent software.
    - os_version string
      The version of the operating system used to access the user agent software.
- session_id string
  Represents the “session” of user activity. Absent if the application was initialized while backgrounded.
- source stringREQUIRED
  Possible values: API
- triggering_push object<Associated push>REQUIRED
  The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.
  An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.
device objectREQUIRED
Holds information about the email device (an individual email channel) the event occurred against.
OBJECT PROPERTIES
- channel string
  The unique, platform-agnostic channel identifier for a device.
- delivery_address stringREQUIRED
  The email address of the channel the event occurred against.
- device_type stringREQUIRED
  Email compliance events use the EMAIL device type.
  Possible values: EMAIL
- named_user string
  The Named User that the channel is associated with; appears only if the channel is associated with a Named User.

Examples

{
  "id": "544da998-9338-4506-8564-8adf7b2597cf",
  "offset": "1000032367699",
  "occurred": "2020-07-29T20:26:03.000Z",
  "processed": "2020-07-29T20:27:47.780Z",
  "device": {
    "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
    "device_type": "EMAIL",
    "delivery_address": "new.subscriber@example.com",
    "named_user_id": "a_person"
  },
  "body": {
    "name": "initial_open",
    "triggering_push": {
      "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99"
    },
    "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
    "source": "API",
    "properties": {
      "sender": "baseball@example.com",
      "subject": "Baseball Season is Almost Here!",
      "email": "new.subscriber@example.com",
      "os_family": "Android",
      "is_mobile": "true",
      "device_brand": "Motorola",
      "os_version": "11",
      "device_family": "moto g stylus",
      "is_prefetched": "false",
      "agent_family": "Chrome"
    }
  },
  "type": "CUSTOM"
}

Email injection event

This event occurs when the provider (SparkPost) receives a message — typically when a member of the audience responds to an email.

Jump to examples ↓

OBJECT PROPERTIES

body objectREQUIRED
OBJECT PROPERTIES
- name stringREQUIRED
  Possible values: injection
- properties objectREQUIRED
  OBJECT PROPERTIES
  - email string
    The recipient’s email address.
  - sender string
    The sender of the email specified by the event.
  - subject string
    The subject line of the email specified by the event.
- session_id string
  Represents the “session” of user activity. Absent if the application was initialized while backgrounded.
- source stringREQUIRED
  Possible values: API
- triggering_push object<Associated push>REQUIRED
  The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.
  An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.
device objectREQUIRED
Holds information about the email device (an individual email channel) the event occurred against.
OBJECT PROPERTIES
- channel string
  The unique, platform-agnostic channel identifier for a device.
- delivery_address stringREQUIRED
  The email address of the channel the event occurred against.
- device_type stringREQUIRED
  Email compliance events use the EMAIL device type.
  Possible values: EMAIL
- named_user string
  The Named User that the channel is associated with; appears only if the channel is associated with a Named User.

Used in:

Open an event stream

Examples

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@example.com"
  },
  "body": {
      "name": "injection",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@example.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "new.subscriber@example.com"
      }
  },
  "type": "CUSTOM"
}

Email open event

Occurs when a recipient opens an email, rendering a tracking pixel at the bottom of the message. If a message is truncated by a client or email provider, a user may have to open it in a separate window to render the tracking pixel (and register this event).

Jump to examples ↓

OBJECT PROPERTIES

body objectREQUIRED
OBJECT PROPERTIES
- name stringREQUIRED
  Possible values: open
- properties objectREQUIRED
  All of
  - OBJECT PROPERTIES
    - email string
      The recipient’s email address.
    - sender string
      The sender of the email specified by the event.
    - subject string
      The subject line of the email specified by the event.
  - OBJECT PROPERTIES
    - agent_family string
      The name of the family of user agent software used to access the email, e.g., WebKit
    - device_brand string
      The brand of the device that was used to access the user agent software, e.g., Samsung or Apple.
    - device_family string
      The name of the device used to access the user agent software.
    - is_mobile boolean
      Indicates whether or not the user agent is from a mobile device.
    - is_prefetched boolean
      Indicates if this event was likely prefetched, for example through Apple MPP. This field does not apply to clicks. The value returned in click events is always false.
    - os_family string
      The name of the operating system used to access the user agent software.
    - os_version string
      The version of the operating system used to access the user agent software.
- session_id string
  Represents the “session” of user activity. Absent if the application was initialized while backgrounded.
- source stringREQUIRED
  Possible values: API
- triggering_push object<Associated push>REQUIRED
  The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.
  An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.
device objectREQUIRED
Holds information about the email device (an individual email channel) the event occurred against.
OBJECT PROPERTIES
- channel string
  The unique, platform-agnostic channel identifier for a device.
- delivery_address stringREQUIRED
  The email address of the channel the event occurred against.
- device_type stringREQUIRED
  Email compliance events use the EMAIL device type.
  Possible values: EMAIL
- named_user string
  The Named User that the channel is associated with; appears only if the channel is associated with a Named User.

Used in:

Open an event stream

Examples

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@example.com"
  },
  "body": {
      "name": "open",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
          "sender": "baseball@example.com",
          "subject": "Baseball Season is Almost Here!",
          "email": "new.subscriber@example.com",
          "os_family": "Android",
          "is_mobile": "true",
          "device_brand": "Motorola",
          "os_version": "11",
          "device_family": "moto g stylus",
          "is_prefetched": "false",
          "agent_family": "Chrome"
      }
  },
  "type": "CUSTOM"
}

Email unsubscribe link event

Occurs when a user clicks an unsubscribe link in an email you sent.

Jump to examples ↓

OBJECT PROPERTIES

body objectREQUIRED
OBJECT PROPERTIES
- name stringREQUIRED
  Possible values: unsubscribe
- properties objectREQUIRED
  OBJECT PROPERTIES
  - unsubscribe_event_type string
    Possible values: link_unsubscribe
- session_id string
  Represents the “session” of user activity. Absent if the application was initialized while backgrounded.
- source stringREQUIRED
  Possible values: API
- triggering_push object<Associated push>REQUIRED
  The specific push_id and accompanying identifiers associated with an event. An associated push helps you trace an event to the original notification or operation.
  An associated push object may specify a time, if the push was a singular operation sent at a defined time. Otherwise, the object will include a group_id if the push was sent at a relative time (best_time or local_time) an automation pipeline, or another operation resulting in multiple push_ids.
device objectREQUIRED
Holds information about the email device (an individual email channel) the event occurred against.
OBJECT PROPERTIES
- channel string
  The unique, platform-agnostic channel identifier for a device.
- delivery_address stringREQUIRED
  The email address of the channel the event occurred against.
- device_type stringREQUIRED
  Email compliance events use the EMAIL device type.
  Possible values: EMAIL
- named_user string
  The Named User that the channel is associated with; appears only if the channel is associated with a Named User.

Used in:

Open an event stream

Examples

{
  "id": "2cf89e3a-2458-4c2d-8fcf-11f593b1b85e",
  "offset": "1000001778145",
  "occurred": "2019-02-27T23:20:14.000Z",
  "processed": "2019-02-27T23:20:49.347Z",
  "device": {
      "channel": "b8519372-54ff-456d-9819-7faa92fe8b9d",
      "device_type": "EMAIL",
      "delivery_address": "new.subscriber@example.com"
  },
  "body": {
      "name": "unsubscribe",
      "triggering_push": {
          "push_id": "bd5b54a8-84bd-40bc-aa84-8315f9300a99",
          "campaigns": {
              "categories": [
                  "new",
                  "Baseball Fan"
              ]
          }
      },
      "session_id": "19e09be8-a586-4ff8-940f-1a4084d928e9",
      "source": "API",
      "properties": {
        "unsubscribe_event_type": "link_unsubscribe"
      }
  },
  "type": "CUSTOM"
}