Compliance Event Stream

Open a compliance event stream

Opens a stream delivering events proving data-safety regulation compliance for email and SMS channel-related events (registration, unsubscription, etc.).

Unlike a standard event stream, a compliance event stream uses basic authorization, like API calls to https://go.urbanairship.com/api.

Jump to examples ↓

POST /api/events/general

Security:

Request headers:

• X-UA-Appkey stringREQUIRED
  The App Key for the project you want to return compliance events for.

Request body:

• Content-Type: application/json

  Compliance request

  A request for compliance events is much like a request to /api/events, but has a limited scope.

Responses

• 200

  The response to a successful request is an unending stream of newline-delimited JSON . Each non-empty line in the response represents a single compliance event. Unlike events in a normal event stream, this endpoint returns events of the compliance type, and is open to SMS and email customers. As long as the connection is open, Airship will continue to write to the event stream.

  If a stream records no events for a period of time, the API will write a blank line (a single newline character) to the connection to prevent it from being closed for inactivity. If the enable_offset_updates field in the request is true, then the blank line is replaced with an OFFSET_UPDATE event. These events have no body or device field, and always have occurred and processed times indicating when they were sent. The offset field will contain the offset of the last event considered for inclusion in the stream whether or not it was actually sent. This may be useful to track position in the stream when using a filter which removes much of it.

  You should not store these events; they will be different for every connection even if requests are identical. OFFSET_UPDATE events are not subject to filters, and are delivered even if not specified in the list of events you want to return. You should always check the type field before handling any delivered event.

  If you do not receive data or new line characters for ninety seconds, close the connection and reconnect.

  Response body:

  • Content-Type: application/vnd.urbanairship+x-ndjson; version=3;

    Events relating to regulatory compliance for email and SMS channels.

    All of
    • OBJECT PROPERTIES
      • id stringREQUIRED

        Uniquely identifies an event. The data stream will occasionally send duplicate events. Duplicate events will have the same id, type, occurred, device, and body values but different offset and processed values. You should use the id to deduplicate.

      • occurred stringREQUIRED

        When the event occurred.

      • offset string

        An identifier of a location in the stream; used to resume the stream after severing a connection. If you open a stream using the offset value, the stream will resume with the next element in the stream. You should store this value as a string so that you can easily resume the stream if it ends for any reason.

      • processed stringREQUIRED

        When the event was ingested by Airship. There may be some latency between when the event occurred, and when it was processed.

      • type stringREQUIRED

        Compliance events are the only types of events returned by this event stream.

        Possible values: COMPLIANCE

Examples

POST /api/events/general HTTP/1.1
Authorization: Basic <master authorization string>
X-UA-Appkey: <appkey>
Accept: application/vnd.urbanairship+x-ndjson; version=3;
Content-Type: application/json

{
  "start":"LATEST",
  "enable_offset_updates": true
}

HTTP/1.1 200 OK
Content-encoding: gzip
Content-Type: application/vnd.urbanairship+json; version=3;

{
  "id": "9781ff2e-fa4a-4fa8-bd9d-41f318c48963",
  "offset": "1000001778910",
  "occurred": "2018-11-28T00:02:41.794Z",
  "processed": "2018-11-28T00:02:45.270Z",
  "device": {
      "channel": "5a39b6d8-0a5a-4c2b-a4a0-3d4a71e5254b",
      "device_type": "EMAIL",
      "delivery_address": "bogus@example.com"
  },
  "body": {
      "event_type": "bounce",
      "properties": {
          "bounce_event_type": "bounce",
          "sender": "msprvs1=17870ayYKWpBI=bounces-179492-4@example.com",
          "subject": "You there?",
          "email": "bogus@example.com",
          "bounce_class": "10"
      }
  },
  "type": "COMPLIANCE"
}