GreenArrow Email Software Documentation

Users API

User Attributes

id

integer

/

read-only

Internal identifier for this users.

full_name

string

/

required

Full name of this user.

  • Must be present and a maximum of 100 charaters in length.
email

string

/

required

Email address for this user.

  • Must be present and a valid email address.
  • Must be unique across the system.
  • Email addresses with international domain names are not supported.
active

boolean

/

required

True or false if this user can sign in.

role

string

/

required

Role of the user.

  • May be: system_admin, organization_admin, or standard
  • System administrators may only exist on the System Organization (ID = 1)
show_quick_tips

boolean

/

default: true

The user sees tips in the UI.

default_preview_recipients

array of strings

The email addresses that will be automatically filled in when sending preview emails.

  • Setting this field to null will clear to a blank array ([]).
  • May contain at most 100 email addresses.
terms_and_conditions_version

integer

The Terms & Conditions version number to which this user has agreed. A value of null indicates either the user has not agreed or the Terms & Conditions feature is not enabled.

If either of following is true, the user will be required to agree to the current Terms & Conditions the next time they interact with GreenArrow Studio:

  • The user’s terms_and_conditions_version is null.

  • The user’s terms_and_conditions_version is less than the current version number and the Require on Updates option is set.

Set this to a value larger than any version number you might use to prevent the user from ever being required to agree.

If Terms & Conditions was previously enabled, then later disabled, this value might not be null when sent from the server. The API user may continue to carry this number forward or clear it to null.

  • Must be either null or a non-negative integer.
  • May only be set if the Terms & Conditions feature is enabled.
  • System Administrators are not required to agree to the Terms & Conditions.
permissions

hash



The permissions hash has an entry for each of the following keys with the values being the available permissions.

Here’s an example of a valid permissions hash.

        {
          "mailing_list": [ "update" ],
          "autoresponder": [ "update" ],
          "seed_list": [ "create", "update", "delete" ]
        }

mailing_list

array of strings

Valid options: create, update, delete.

subscriber

array of strings

Valid options: create, update, delete, read, import, export.

segmentation_criteria

array of strings

Valid options: create, update, delete.

autoresponder

array of strings

Valid options: create, update, delete, update_state, read_stats.

web_form

array of strings

Valid options: create, update, delete.

custom_field

array of strings

Valid options: create, update, delete.

campaign

array of strings

Valid options: create, update, delete, send, update_state, read_stats.

campaign/template

array of strings

Valid options: create, update, delete.

seed_list

array of strings

Valid options: create, update, delete.

Get a List of Users

Get a list of the basic details of login users.

URL

GET /ga/api/v2/users
GET /ga/api/v2/organizations/:organization_id/users

When accessed by a system admin, the /ga/api/v2/users endpoint will return all users system wide. If a system admin account needs to retrieve the users on a single organization, use the /ga/api/v2/organizations/:organization_id/users endpoint.

When accessed by any other API user, the /ga/api/v2/users endpoint will return the users on their organization.

Request Parameters

full_name

string

Filter all users with that exact description (case insensitive).

full_name_contains

string

Filter all users that contain that description (case insensitive).

email

string

Filter all users with that exact email (case insensitive).

email_contains

string

Filter all users that contain that email (case insensitive).

order_by

string

Specify an api key field to sort the results by. Can be full_name, email, or id. full_name and email will be ordered case-insensitively.

Defaults to id

Response

The response will be a JSON array where each element contains the “User Attributes” specified above.

This endpoint returns paginated records with a default page size of 2000.

Example

GET /ga/api/v2/users

HTTP/1.1 200 OK

{
  "success": true,
  "data": [
    {
      "id": 54,
      "full_name": "John Smith",
      "email": "[email protected]",
      "active": true,
      "role": "system_admin",
      "show_quick_tips": true,
      "permissions": {
        "mailing_list": [
          "create",
          "update",
          "delete"
        ],
        "subscriber": [
          "create",
          "update",
          "delete",
          "read",
          "import",
          "export"
        ],
        "segmentation_criteria": [
          "create",
          "update",
          "delete"
        ],
        "autoresponder": [
          "create",
          "update",
          "delete",
          "update_state",
          "read_stats"
        ],
        "web_form": [
          "create",
          "update",
          "delete"
        ],
        "custom_field": [
          "create",
          "update",
          "delete"
        ],
        "campaign": [
          "create",
          "update",
          "delete",
          "send",
          "update_state",
          "read_stats"
        ],
        "campaign/template": [
          "create",
          "update",
          "delete"
        ],
        "seed_list": [
          "create",
          "update",
          "delete"
        ]
      },
      "default_preview_recipients": [

      ]
    },
    {
      "id": 55,
      "full_name": "William Green",
      "email": "[email protected]",
      "active": true,
      "role": "system_admin",
      "show_quick_tips": true,
      "permissions": {
        "mailing_list": [
          "create",
          "update",
          "delete"
        ],
        "subscriber": [
          "create",
          "update",
          "delete",
          "read",
          "import",
          "export"
        ],
        "segmentation_criteria": [
          "create",
          "update",
          "delete"
        ],
        "autoresponder": [
          "create",
          "update",
          "delete",
          "update_state",
          "read_stats"
        ],
        "web_form": [
          "create",
          "update",
          "delete"
        ],
        "custom_field": [
          "create",
          "update",
          "delete"
        ],
        "campaign": [
          "create",
          "update",
          "delete",
          "send",
          "update_state",
          "read_stats"
        ],
        "campaign/template": [
          "create",
          "update",
          "delete"
        ],
        "seed_list": [
          "create",
          "update",
          "delete"
        ]
      },
      "default_preview_recipients": [

      ]
    },
    {
      "id": 56,
      "full_name": "Joe Johnson",
      "email": "[email protected]",
      "active": true,
      "role": "system_admin",
      "show_quick_tips": true,
      "permissions": {
        "mailing_list": [
          "create",
          "update",
          "delete"
        ],
        "subscriber": [
          "create",
          "update",
          "delete",
          "read",
          "import",
          "export"
        ],
        "segmentation_criteria": [
          "create",
          "update",
          "delete"
        ],
        "autoresponder": [
          "create",
          "update",
          "delete",
          "update_state",
          "read_stats"
        ],
        "web_form": [
          "create",
          "update",
          "delete"
        ],
        "custom_field": [
          "create",
          "update",
          "delete"
        ],
        "campaign": [
          "create",
          "update",
          "delete",
          "send",
          "update_state",
          "read_stats"
        ],
        "campaign/template": [
          "create",
          "update",
          "delete"
        ],
        "seed_list": [
          "create",
          "update",
          "delete"
        ]
      },
      "default_preview_recipients": [

      ]
    },
    {
      "id": 57,
      "full_name": "MyString",
      "email": "[email protected]",
      "active": true,
      "role": "system_admin",
      "show_quick_tips": true,
      "permissions": {
        "mailing_list": [
          "create",
          "update",
          "delete"
        ],
        "subscriber": [
          "create",
          "update",
          "delete",
          "read",
          "import",
          "export"
        ],
        "segmentation_criteria": [
          "create",
          "update",
          "delete"
        ],
        "autoresponder": [
          "create",
          "update",
          "delete",
          "update_state",
          "read_stats"
        ],
        "web_form": [
          "create",
          "update",
          "delete"
        ],
        "custom_field": [
          "create",
          "update",
          "delete"
        ],
        "campaign": [
          "create",
          "update",
          "delete",
          "send",
          "update_state",
          "read_stats"
        ],
        "campaign/template": [
          "create",
          "update",
          "delete"
        ],
        "seed_list": [
          "create",
          "update",
          "delete"
        ]
      },
      "default_preview_recipients": [

      ]
    }
  ],
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 2000,
  "num_records": 4,
  "num_pages": 1
}

Get a Single User

Get all the basic details of a single user.

URL

GET /ga/api/v2/users/:id

Request Parameters

id

integer

The id of the user to get

Response

The response will be a JSON hash as described in the User Attributes section of this document.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

GET /ga/api/v2/users/58

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 58,
    "full_name": "John Smith",
    "email": "[email protected]",
    "active": true,
    "role": "system_admin",
    "show_quick_tips": true,
    "permissions": {
      "mailing_list": [
        "create",
        "update",
        "delete"
      ],
      "subscriber": [
        "create",
        "update",
        "delete",
        "read",
        "import",
        "export"
      ],
      "segmentation_criteria": [
        "create",
        "update",
        "delete"
      ],
      "autoresponder": [
        "create",
        "update",
        "delete",
        "update_state",
        "read_stats"
      ],
      "web_form": [
        "create",
        "update",
        "delete"
      ],
      "custom_field": [
        "create",
        "update",
        "delete"
      ],
      "campaign": [
        "create",
        "update",
        "delete",
        "send",
        "update_state",
        "read_stats"
      ],
      "campaign/template": [
        "create",
        "update",
        "delete"
      ],
      "seed_list": [
        "create",
        "update",
        "delete"
      ]
    },
    "default_preview_recipients": [

    ]
  },
  "error_code": null,
  "error_message": null
}

Create a New User

Create a new user on the current organization.

URL

POST /ga/api/v2/users

Request Parameters

The request body should be a JSON hash as described in the User Attributes section of this document.

Response

The response will be a JSON object in the same format as the response to the users index.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

POST /ga/api/v2/users

{
  "user": {
    "password1": "password",
    "password2": "password",
    "full_name": "My new user",
    "email": "[email protected]",
    "active": true,
    "role": "standard"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 66,
    "full_name": "My new user",
    "email": "[email protected]",
    "active": true,
    "role": "standard",
    "show_quick_tips": true,
    "permissions": {
      "mailing_list": [
        "create",
        "update",
        "delete"
      ],
      "subscriber": [
        "create",
        "update",
        "delete",
        "read",
        "import",
        "export"
      ],
      "segmentation_criteria": [
        "create",
        "update",
        "delete"
      ],
      "autoresponder": [
        "create",
        "update",
        "delete",
        "update_state",
        "read_stats"
      ],
      "web_form": [
        "create",
        "update",
        "delete"
      ],
      "custom_field": [
        "create",
        "update",
        "delete"
      ],
      "campaign": [
        "create",
        "update",
        "delete",
        "send",
        "update_state",
        "read_stats"
      ],
      "campaign/template": [
        "create",
        "update",
        "delete"
      ],
      "seed_list": [
        "create",
        "update",
        "delete"
      ]
    },
    "default_preview_recipients": [

    ],
    "terms_and_conditions_version": null
  },
  "error_code": null,
  "error_message": null
}

Update an Existing User

URL

PUT /ga/api/v2/users/:id

Request Parameters

The request body should be a JSON hash as described in the User Attributes section of this document.

Response

The response will be a JSON object in the same format as the response to the users index.

Example

PUT /ga/api/v2/users/67

{
  "user": {
    "full_name": "My updated name"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 67,
    "full_name": "My updated name",
    "email": "[email protected]",
    "active": true,
    "role": "system_admin",
    "show_quick_tips": true,
    "permissions": {
      "mailing_list": [
        "create",
        "update",
        "delete"
      ],
      "subscriber": [
        "create",
        "update",
        "delete",
        "read",
        "import",
        "export"
      ],
      "segmentation_criteria": [
        "create",
        "update",
        "delete"
      ],
      "autoresponder": [
        "create",
        "update",
        "delete",
        "update_state",
        "read_stats"
      ],
      "web_form": [
        "create",
        "update",
        "delete"
      ],
      "custom_field": [
        "create",
        "update",
        "delete"
      ],
      "campaign": [
        "create",
        "update",
        "delete",
        "send",
        "update_state",
        "read_stats"
      ],
      "campaign/template": [
        "create",
        "update",
        "delete"
      ],
      "seed_list": [
        "create",
        "update",
        "delete"
      ]
    },
    "default_preview_recipients": [

    ]
  },
  "error_code": null,
  "error_message": null
}


Copyright © 2012–2019 GreenArrow Email