Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

EmailX API Access #37

Open
zarathustra323 opened this issue May 15, 2020 · 0 comments
Open

EmailX API Access #37

zarathustra323 opened this issue May 15, 2020 · 0 comments

Comments

@zarathustra323
Copy link
Member

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.”
image (1)

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: "[email protected]",
    password: "yourpassword"
  }) {
    session {
      token
    }
  }
}

Response:

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

Playground Example:
image (2)

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:
image (3)

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):
image (4)

To generate an end date of April 30th, 2020 11:59:59 PM:
image (5)

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant