EmailX API Access

[zarathustra323]

EmailX API

Note: GraphQL Playground is used for interactively accessing the EmailX GraphQL API. It can be downloaded and installed from https://www.electronjs.org/apps/graphql-playground

Ultimately you’ll need to access the API programmatically for retrieving the data and storing it for use in your application.

All EmailX API calls should be made using POST requests to:
https://acbm.email-x.io/graphql

Using GraphQL Playground

Once installed from https://www.electronjs.org/apps/graphql-playground open the application, select “URL Endpoint,” enter the ACBM GraphQL URL, and then click “Open.”

Step 1: Authenticate

In order to access data from the EmailX API you must first authenticate/login. Once submitted, you will receive an authentication token. This token must be added to all subsequent API requests:

Request:

mutation {
  loginUser(input: {
    email: "your-email@domain.com",
    password: "yourpassword"
  }) {
    session {
      token
    }
  }
}

Response:

{
  "data": {
    "loginUser": {
      "session": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI2ODc3NmY0Mi00NzFmLTUxNmQtYjU3OC1kOGI3YzNiMGU0OWEiLCJleHAiOjE1ODkzODY1NTAsImlhdCI6MTU4OTMwMDE1MH0.Zt8U-4e6ISBUwbWhxvuX08YfTtvpW56p4VtojuM2JGo"
      }
    }
  }
}

Playground Example:

Step 2: Retrieve data via the “report” query

The report API query returns impression and click data for a specified date range. The two most import query inputs are the start and end parameters. When combined, these inputs will return data (inclusively) for the specified date range. Both the start and end date inputs need to be provided as UNIX timestamps with milliseconds (more on that below). Queries to this API must include an authorization header that provides the token you retrieved in Step 1.

For example, to query data for all of April 2020

Request:

query {
  report(input: {
    start: 1585717200000,
    end: 1588309199000
  }) {
    rows {
      advertiser {
        id
        name
      }
      order {
        id
        name
      }
      lineitem {
        id
        name
      }
      ad {
        id
        name
        size
      }
      publisher {
        id
        name
      }
      deployment {
        id
        name
      }
      adunit {
        id
        name
        size
      }
      impressions
      clicks
      ctr
    }
  }
}

Request Headers:

{
  "authorization": "Bearer [the auth token from step 1, without these surrounding brackets]"
}

Response (truncated for brevity):

{
  "data": {
    "report": {
      "rows": [
        {
          "advertiser": {
            "id": "5ca61c0bc15d7e47f2be29b4",
            "name": "Informa"
          },
          "order": {
            "id": "5ca61c46a2fb1054b046ad8e",
            "name": "SDC_INFORMA_MSG-4819"
          },
          "lineitem": {
            "id": "5ca61c71c15d7e289fbe29ed",
            "name": "SDC_RNL-HEADLINE-NEWS_LB-P_20190405-20190415"
          },
          "ad": {
            "id": "5ca61cb3c15d7e691dbe2a2c",
            "name": "SDC_INTERNET-OF-THINGS_600X100",
            "size": "600x100"
          },
          "publisher": {
            "id": "5c51c1389bcbcf2343dc97e8",
            "name": "SDCExec"
          },
          "deployment": {
            "id": "5c51c1fd58ff69468155d0da",
            "name": "Headline News"
          },
          "adunit": {
            "id": "5c51c2469bcbcf1119dc9816",
            "name": "LB - Primary",
            "size": "600x100"
          },
          "impressions": 1,
          "clicks": 0,
          "ctr": 0
        },
        {
          "advertiser": {
            "id": "5dadf85fc1a3afb42a97ead9",
            "name": "Descartes"
          },
          "order": {
            "id": "5dadf87abccb5b2f5d6eb561",
            "name": "FL_DESCARTES_MSG-5302"
          },
          "lineitem": {
            "id": "5dadf8a0c1a3afd33297eb09",
            "name": "FL_RNL-TODAYS-NEWS_20191023-20191025_1023"
          },
          "ad": {
            "id": "5dadf8f8c1a3af1fc397eb44",
            "name": "FL_BY-AN-AVERAGE-OF-7%_600X100",
            "size": "600x100"
          },
          "publisher": {
            "id": "5c59a2ad465d192d75ab8376",
            "name": "Food Logistics"
          },
          "deployment": {
            "id": "5c59a2d55a66dbbc89d477ea",
            "name": "Today's News"
          },
          "adunit": {
            "id": "5c59a2f5465d1901d2ab83a4",
            "name": "LB - Primary",
            "size": "600x100"
          },
          "impressions": 1,
          "clicks": 0,
          "ctr": 0
        }
      ]
    }
  }
}

Playground Example:

Generating dates

When accessing this data programmatically, you’ll need to determine the best way to generate the start and end timestamps. For purposes of trying out the API using the playground, the best way to generate timestamps (with milliseconds) is to use an online tool such as https://www.epochconverter.com/

On Epoch Converter, select the date and time for your start and end dates - using your Local Time (not GMT). This will output the “Timestamp in milliseconds” that you can copy and paste into the GraphQL playground.

To generate a start date of April 1st, 2020 midnight (12:00 am):

To generate an end date of April 30th, 2020 11:59:59 PM:

Note: you can query any date range, but ranges longer than a month will be quite slow to generate. It’s recommended that you pick smaller ranges for efficiency purposes, perhaps for a single day (and run it each day) or for a single week (and run it each week).