Engine Users API

Table of Contents
Overview
Attributes
Get a List of Users
Get Details on a Single User
Create a User
Update a User
Delete a User

Overview

Engine Users provide authenticated access to various aspects of GreenArrow Engine.

Each user contains separate permissions for the following:

Injection (can be limited to HTTP submittion, SMTP submission, all of the above, or none of the above)
API (can be limited to stats-only access, read-only access, full editing privileges, or no access)
UI (can be limited to stats-only access, read-only access, full editing privileges, or no access)

Attributes

The following are the configurable attributes defined for Engine Users.

user
hash
/
required

id
integer
/
read-only

A unique automatically generated identifier.

email
string
/
required

The email address used to identify this user.

Must be present and a valid email address.
Must be unique (case insensitive).

password
string
/
required

The password used for authenticating this user.

permissions
hash
/
required

injection
string
/
required

The access this user has to message injection. May be:

yes (All permissions are granted)
smtp-only (This user may only inject messages via SMTP)
http-only (This user may only inject messages via the HTTP Submission API)
no (This user may not inject messages)

api
string
/
required

The access this user has to the API. May be:

yes (All permissions are granted)
read-only (This user may only access the API in a read-only mode)
stats-only (This user may only access the API for statistics)
no (No permissions are granted)

ui
string
/
required

The access this user has to the user interface. May be:

yes (All permissions are granted)
read-only (This user may only access the UI in a read-only mode)
stats-only (This user may only access the UI for statistics)
no (No permissions are granted)

is_disabled
boolean
/
default: false

This user is disabled. No access to message injection, API, or UI will be provided.

force_mail_class
hash
/
optional

An optional mail class. When this is specified, messages injected by this user will be forced to use the specified mail class (ignoring any mail class requested at the time of injection).

With this configured, the X-GreenArrow-MailClass header is ignored for messages injected by this user.

id integer	The unique identifier of the mail class to enforce.
name string	The unique name of the mail class to enforce.

Get a List of Users

GET /ga/api/v3/eng/users

Parameters

The following parameters are valid for the above endpoint.

page integer / optional	The page number from which to retrieve. Page numbering starts at `0`.
page_token string / optional	The `page_token` to retrieve the next page based on the prior query results.

Examples:

GET /ga/api/v3/eng/users?page={page}
GET /ga/api/v3/eng/users?page_token={page_token}
GET /ga/api/v3/eng/users?name={name}

Response

The response will contain a list of Users in the following format.

users
array of hashes

id integer	An automatically generated identifier.
name string	A descriptive name for this user.

pagination
hash

page integer	The page number of this result set. Page numbers start at 0.
per_page integer	The number of records returned on each page.
num_pages integer	The total number of pages in the result set.
num_records integer	The total number of records that are in the result set.
next_page_token string	A unique identifier that can be used to retrieve the next result set. `null` is returned if this is the last page.

Example

GET /ga/api/v3/eng/users

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "users": [
      {
        "id": 1,
        "email": "[email protected]",
        "permissions": {
          "injection": "yes",
          "api": "yes",
          "ui": "yes"
        },
        "is_disabled": false,
        "force_mail_class": null
      },
      {
        "id": 2,
        "email": "[email protected]",
        "permissions": {
          "injection": "yes",
          "api": "yes",
          "ui": "yes"
        },
        "is_disabled": false,
        "force_mail_class": null
      },
      {
        "id": 3,
        "email": "[email protected]",
        "permissions": {
          "injection": "yes",
          "api": "yes",
          "ui": "yes"
        },
        "is_disabled": false,
        "force_mail_class": {
          "id": 1,
          "name": "my_mail_class_one"
        }
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get Details on a Single User

GET /ga/api/v3/eng/users/{id_or_email}

Parameters

The following parameters are valid for the above endpoint.

id_or_email
string or integer
/
optional

The id_or_email attribute can be either an email address (in which case the user will be found by case-insensitive email address search) or the id integer for the requested user.

Examples:

GET /ga/api/v3/eng/users/123
GET /ga/api/v3/eng/users/[email protected]

Response

The response will contain details on the requested record:

user
hash

The attributes for this hash are defined in the Attributes section of this document.

Example

GET /ga/api/v3/eng/users/9

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "user": {
      "id": 9,
      "email": "[email protected]",
      "permissions": {
        "injection": "yes",
        "api": "yes",
        "ui": "yes"
      },
      "is_disabled": false,
      "force_mail_class": {
        "id": 1,
        "name": "my_mail_class_one"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a User

POST /ga/api/v3/eng/users

Payload

user
hash
/
required

The content of this hash is described in the Attributes section of this page.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Response

The response will include a user key containing the full User record as defined in the User Attributes.

Example

POST /ga/api/v3/eng/users

{
  "user": {
    "email": "[email protected]",
    "password": "greenarrow",
    "permissions": {
      "injection": "smtp-only",
      "api": "stats-only",
      "ui": "read-only"
    },
    "is_disabled": true,
    "force_mail_class": {
      "name": "my_mail_class_one"
    }
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "user": {
      "id": 16,
      "email": "[email protected]",
      "permissions": {
        "injection": "smtp-only",
        "api": "stats-only",
        "ui": "read-only"
      },
      "is_disabled": true,
      "force_mail_class": {
        "id": 1,
        "name": "my_mail_class_one"
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a User

PUT /ga/api/v3/eng/users/{id}

Payload

user
hash
/
required

The content of this hash is described in the Attributes section of this page.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Response

The response will include a user key containing the full user record as defined in the User Attributes.

Example

PUT /ga/api/v3/eng/users/23

{
  "user": {
    "email": "[email protected]"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "user": {
      "id": 23,
      "email": "[email protected]",
      "permissions": {
        "injection": "yes",
        "api": "yes",
        "ui": "yes"
      },
      "is_disabled": false,
      "force_mail_class": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a User

DELETE /ga/api/v3/eng/users/{id}

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/users/26

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
  },
  "error_code": null,
  "error_messages": null
}