GreenArrow Email Software Documentation

Organizations API

Organization Attributes

id

integer

Internal identifier for this organization.
name

string

The name of this organization.

May only be edited by a System Administrator
active

boolean

Whether this organization is active for users to log in.

May only be seen or edited by a System Administrator
anniversary_day

integer

This is a number from 1 to 31 defining the day of the month on which this organization’s message counts will reset.

May only be edited by a System Administrator
time_zone_name

string

The time zone for times in this organization. Example: (GMT-06:00) Central Time (US & Canada)
time_zone_utc_offset

intger

The number of seconds that the timezone is offset from UTC.
html_header

string

The HTML header prepended to all emails sent.
html_footer

string

The HTML footer appended to all emails sent.
text_header

string

The Text header prepended to all emails sent.
text_footer

string

The Text footer appended to all emails sent.
custom_headers

string

These headers are included with all emails sent from this organization. Specify one header per line (separated by \n).

Headers must be one of the following:

  • Any header that begins with X-
  • List-Help
  • CFBL-Address
  • CFBL-Feedback-ID
  • BIMI-Selector

May only be seen or edited by a System Administrator
auto_subscriber_management

hash

These fields will only be present if the server has the “Organizational Auto Subscriber Management” feature flag enabled.

distribute_removals

boolean

/

required

Turning this option on will cause unsubcribes, bounces, and spam complaints on one mailing list to remove that email address from all mailing lists in this organization.
unsub_suppression_list (suppression list

see Suppression List Attributes)

The suppression list which is appended to any time a subscriber unsubscribes.

Set to null to use none.
bounce_suppression_list (suppression list

see Suppression List Attributes)

The suppression list which is appended to any time a which causes a subscriber’s status to be set to bounced occurs.

Set to null to use none.
scomp_suppression_list (suppression list

see Suppression List Attributes)

The suppression list which is appended to any time a subscriber issues a spam complaint.

Set to null to use none.
sending_quota

hash

This field determines if an organization has a monthly email sending limit and what to do when that limit is reached.

May only be seen or edited by a System Administrator

mode

string

/

required

Valid values are:

no_limit

Do not use a sending limit.
hidden_limit

Enforce a limit hidden from the organization’s view.
visible_limit

Set a limit for the organization and automatically notify it when the limit is reached. Upon reaching the limit plus the overage, this organization’s sending is stopped.

The overage field is required with this option.
advisory_message

Display a notice when the sending quota limit is reached, but take no automatic enforcement actions.
fixed_credits

The organization has a total number of emails it may send.
limit

integer

The limit to be used for the selected mode (see above for details).

If this limit is set to 1, autoresponders will neither enqueue nor deliver.

  • Must be set if mode is one of: hidden_limit, visible_limit, advisory_message, fixed_credits

  • Must be an integer greater than or equal to 0

  • Due to caching and performance optimizations, a small number of extra messages may be allowed.
overage

integer

The allowed overage percentage to be used when mode is visible_limit

  • Must be set if mode is: visible_limit

  • Must be an integer greater than or equal to 0
notify_organization_admins

boolean

Notify all organization administrators when a campaign is suspended due to enforcement of the monthly quota. This only applies if there is an enforced limit.
subscriber_quota

hash

Restrict the number of active subscribers in this organization. This limit is applied to subscriber imports, adding subscribers through the API, and manually adding subscribers through the web interface. This limit will not apply to subscription forms.

May only be seen or edited by a System Administrator

mode

string

/

required

Valid values are:

no_limit

Do not use a subscriber quota limit.
visible_limit

Set a limit for the organization and automatically notify it when the limit is reached. Upon reaching the limit plus the overage, this organization’s mailing lists will not accept any new subscribers except via subscription forms.

limit and overage are required when this option is selected.
limit

integer

The soft limit to be used for notifications.

Required if mode is set to visible_limit.

Must be a positive integer between 0 and 1,000,000,000.
overage

integer

The allowed overage before automatically enforcing the subscriber quota limit.

Required if mode is set to visible_limit

Must be a positive integer between 0 and 10,000.
notify_organization_admins

boolean

Notify all organization administrators when the limit is reached. This only applies if mode is set to visible_limit.
permissions

hash

May only be seen or edited by a System Administrator

forced_unsub_tag_mode

string

Determines whether or not this organization is required to include an unsubscribe link in all campaign email content.

Valid values are:

default

Use the system default.
none

Do not require an unsubscribe link.
link

For HTML content, there must be a link that contains only %%unsubscribe_link%% in its href For Text content, the %%unsubscribe_link%% string must exist and be surrounded by whitespace. This requirement may be satisfied by headers and/or footers.

If a campaign is scheduled prior to this (or link_or_token) being enabled, the campaign will be delivered regardless of whether or not it includes an unsubscribe link.

Campaigns that are scheduled after this is enabled will require the unsubscribe link.

If this requirement is satisfied by headers and/or footers, and those headers and/or footers are modified to exclude the unsubscribe link after the campaign is scheduled, the campaign will be paused prior to delivery. The content, headers, and/or footers will need to be edited to include an unsubscribe link before it can be delivered.
link_or_token

In addition to the links described for link, also permit content that contains a link that includes the %%unsubscribe_token%% replacement code.
virtual_mta

hash

The Virtual MTA (often an IP address) from which this organization can send email.

mode

string

/

required

Valid values are:

select_any

Allow users to select any Virtual MTA.
select_some

Allow users to select from the Virtual MTAs specified in virtual_mtas.
hide_one

Always use the Virtual MTA specified in virtual_mta. The “Virtual MTA” field is hidden from users of this organization.
virtual_mta (Virtual MTA

see VirtualMTA attributes)

The single Virtual MTA to use when mode is hide_one
virtual_mtas (array of Virtual MTAs

see Virtual MTA Attributes)

The Virtual MTAs this organization can choose from if mode is select_some.
bounce_email

hash

When an email bounces, or is rejected by the mail server, the error message is sent to the bounce email address.

mode

string

/

required

Valid values are:

select_any

Allow users to select any bounce email.
select_some

Allow users to select from the bounce emails specified in bounce_emails.
hide_one

Always use the bounce email specified in bounce_email. The “Bounce Email” field is hidden from users of this organization.
bounce_email (bounce email

see Bounce Email Attributes)

The single bounce email to use when mode is hide_one
bounce_emails (array of bounce emails

see Bounce Email Attributes)

The bounce emails this organization can choose from if mode is select_some.
url_domain

hash

The domain name that is used for the clickthrough and open URLs in email messages from this organization.

mode

string

/

required

Valid values are:

select_any

Allow users to select any URL domain.
select_some

Allow users to select from the URL domains specified in url_domains.
hide_one

Always use the URL domain specified in url_domain. The “URL Domain” field is hidden from the users of this organization.
url_domain (URL domain

see URL Domain Attributes)

The single URL domain to use when mode is hide_one
url_domains (array of URL domains

see URL Domain Attributes)

The URL domains this organization can choose from if mode is select_some.
email_address

hash

The list of domains or email addresses that this organization may use in the From Email, Reply To, and Sender Email fields. To allow an organization to use any address on a domain, enter the domain prefixed with an @ symbol like "@domain.com".

mode

string

/

required

Valid values are:

select_any

Allow users to use any email address.
select_some

Allow users to select from the addresses and domains specified in addresses.
addresses

array of strings

A list of email addresses and domains which this organization can use email addresses from.

Format is "[email protected]" to allow this address or "@example.com" to allow any @example.com email address.
special_sending_rule

hash

Define if this organization has access to Special Sending Rules.

mode

string

/

required

Valid values are:

select_any

Enable drop-downs to select any Special Sending Rule.
none

Hide the existence of Special Sending Rules from this organization.
remote_database_connection

hash

The remote database connections with which this organization can create Remote Lists.

mode

string

/

required

Valid values are:

select_any

Allow users to select any database connection.
select_some

Allow users to select from the database connections specified in remote_database_connections.
none

This organization may not use Remote Lists.
remote_database_connections

array of Database Connections

The database connections this organization can choose from if mode is select_some.
speed

integer or string

Campaigns to mailing lists in this organization are throttled to this many messages per hour. Set to "select_any" to allow this organization to set their own speed.

Setting this to anything other than "select_any" will hide the “Speed” field from users of this organization.

  • Must be a positive integer or the string "select_any".

  • Set to 0 for un-throttled.
can_edit_header_and_footer

boolean

/

required

An organization’s header and footer gets automatically added to every email sent from that organization.

Allows this organization to edit its headers and footers.

Other Models Referenced Within Organization

These other models are referenced from within the organization API as specified above. Within data recieved to create or update an organization, these references can be changed to a different model using the same structure as the API will return. The references will look only at the attributes listed below (except for readonly attributes) and will prioritize the highest attribute in each table.

Suppression List Attributes

id

integer

Internal identifier for this supression list.
name

string

The name of this supression list.

Virtual MTA Attributes

id

integer

Internal identifier for this Virtual MTA.
name

string

The name of this Virtual MTA.
type

string

/

readonly

The type of Virtual MTA this object is.

  • May be: ip_address, relay_server, or routing_rule

Bounce Email Attributes

id

integer

Internal identifier for this bounce email.
email

string

The bounce email address.

URL Domain Attributes

id

integer

Internal identifier for this URL domain.
domain

string

The domain

Database Connection Attributes

id

integer

Internal identifier for this database connection.
name

string

The name for this database connection.

Get a List of Organizations

URL

GET /ga/api/v2/organizations

Request Parameters

You can send optional query string parameters using the following attributes:

name

string

Filter the list of organizations to those with this exact (case-insensitive) name.

Cannot be sent along with name_contains.
name_contains

string

Filter the list of organizations to those whose name contains this value (case-insensitive).

Cannot be sent along with name.
minimal

boolean

If true, organizations returned will dispaly only their id and name.
order_by

string

Specify an organization field to sort the results by. Can be name or id.

Defaults to id.

For example to search for organizations whose names contain the string "school":

GET /ga/api/v2/organizations?name_contains=school

Response

The response is a JSON array where each element contains an Organization Object.

This endpoint returns paginated records.

Example 1

GET /ga/api/v2/organizations


HTTP/1.1 200 OK


{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "System Organization",
      "anniversary_day": 1,
      "time_zone_name": "(GMT-06:00) Central Time (US & Canada)",
      "time_zone_utc_offset": -21600,
      "active": true,
      "html_header": "",
      "html_footer": "",
      "text_header": "",
      "text_footer": "",
      "custom_headers": "",
      "permissions": {
        "forced_unsub_tag_mode": "default",
        "virtual_mta": {
          "mode": "select_any"
        },
        "bounce_email": {
          "mode": "select_any"
        },
        "url_domain": {
          "mode": "select_any"
        },
        "email_address": {
          "mode": "select_any"
        },
        "special_sending_rule": {
          "mode": "select_any"
        },
        "remote_database_connection": {
          "mode": "select_any"
        },
        "speed": "select_any",
        "can_edit_header_and_footer": true
      },
      "auto_subscriber_management": {
        "distribute_removals": false,
        "unsub_suppression_list": null,
        "bounce_suppression_list": null,
        "scomp_suppression_list": null
      },
      "sending_quota": {
        "mode": "no_limit"
      },
      "subscriber_quota": {
        "mode": "no_limit"
      }
    },
    {
      "id": 2,
      "name": "An Organization",
      "anniversary_day": 1,
      "time_zone_name": "(GMT-06:00) Central Time (US & Canada)",
      "time_zone_utc_offset": -21600,
      "active": true,
      "html_header": "",
      "html_footer": "",
      "text_header": "",
      "text_footer": "",
      "custom_headers": "",
      "permissions": {
        "forced_unsub_tag_mode": "default",
        "virtual_mta": {
          "mode": "select_any"
        },
        "bounce_email": {
          "mode": "select_any"
        },
        "url_domain": {
          "mode": "select_any"
        },
        "email_address": {
          "mode": "select_any"
        },
        "special_sending_rule": {
          "mode": "select_any"
        },
        "remote_database_connection": {
          "mode": "none"
        },
        "speed": "select_any",
        "can_edit_header_and_footer": true
      },
      "auto_subscriber_management": {
        "distribute_removals": false,
        "unsub_suppression_list": null,
        "bounce_suppression_list": null,
        "scomp_suppression_list": null
      },
      "sending_quota": {
        "mode": "no_limit"
      },
      "subscriber_quota": {
        "mode": "no_limit"
      }
    },
    {
      "id": 3,
      "name": "Second Org",
      "anniversary_day": 1,
      "time_zone_name": "(GMT-06:00) Central Time (US & Canada)",
      "time_zone_utc_offset": -21600,
      "active": true,
      "html_header": "",
      "html_footer": "",
      "text_header": "",
      "text_footer": "",
      "custom_headers": "",
      "permissions": {
        "forced_unsub_tag_mode": "default",
        "virtual_mta": {
          "mode": "select_any"
        },
        "bounce_email": {
          "mode": "select_any"
        },
        "url_domain": {
          "mode": "select_any"
        },
        "email_address": {
          "mode": "select_any"
        },
        "special_sending_rule": {
          "mode": "select_any"
        },
        "remote_database_connection": {
          "mode": "none"
        },
        "speed": "select_any",
        "can_edit_header_and_footer": true
      },
      "auto_subscriber_management": {
        "distribute_removals": false,
        "unsub_suppression_list": null,
        "bounce_suppression_list": null,
        "scomp_suppression_list": null
      },
      "sending_quota": {
        "mode": "no_limit"
      },
      "subscriber_quota": {
        "mode": "no_limit"
      }
    },
    {
      "id": 4,
      "name": "Third Org",
      "anniversary_day": 1,
      "time_zone_name": "(GMT-06:00) Central Time (US & Canada)",
      "time_zone_utc_offset": -21600,
      "active": true,
      "html_header": "",
      "html_footer": "",
      "text_header": "",
      "text_footer": "",
      "custom_headers": "",
      "permissions": {
        "forced_unsub_tag_mode": "default",
        "virtual_mta": {
          "mode": "select_any"
        },
        "bounce_email": {
          "mode": "select_any"
        },
        "url_domain": {
          "mode": "select_any"
        },
        "email_address": {
          "mode": "select_any"
        },
        "special_sending_rule": {
          "mode": "select_any"
        },
        "remote_database_connection": {
          "mode": "none"
        },
        "speed": "select_any",
        "can_edit_header_and_footer": true
      },
      "auto_subscriber_management": {
        "distribute_removals": false,
        "unsub_suppression_list": null,
        "bounce_suppression_list": null,
        "scomp_suppression_list": null
      },
      "sending_quota": {
        "mode": "no_limit"
      },
      "subscriber_quota": {
        "mode": "no_limit"
      }
    }
  ],
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "num_records": 4,
  "num_pages": 1
}

Example 2

GET /ga/api/v2/organizations?minimal=true


HTTP/1.1 200 OK


{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "System Organization"
    },
    {
      "id": 2,
      "name": "An Organization"
    },
    {
      "id": 3,
      "name": "Second Org"
    },
    {
      "id": 4,
      "name": "Third Org"
    }
  ],
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "num_records": 4,
  "num_pages": 1
}

Example 3

GET /ga/api/v2/organizations?minimal=true&name=Third+Org


HTTP/1.1 200 OK


{
  "success": true,
  "data": [
    {
      "id": 4,
      "name": "Third Org"
    }
  ],
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "num_records": 1,
  "num_pages": 1
}

Example 4

GET /ga/api/v2/organizations?minimal=true&name_contains=third


HTTP/1.1 200 OK


{
  "success": true,
  "data": [
    {
      "id": 4,
      "name": "Third Org"
    }
  ],
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "num_records": 1,
  "num_pages": 1
}

Get a Single Organization

Get all the basic details of a single organization.

URL

GET /ga/api/v2/organizations/:id

Request Parameters

id

integer

The id of the organization

Response

The response body is a JSON hash of Organization Attributes.

Example

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

GET /ga/api/v2/organizations/6


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "id": 6,
    "name": "Daily News Co.",
    "anniversary_day": 1,
    "time_zone_name": "(GMT-06:00) Central Time (US & Canada)",
    "time_zone_utc_offset": -21600,
    "active": true,
    "html_header": "",
    "html_footer": "",
    "text_header": "",
    "text_footer": "",
    "custom_headers": "",
    "permissions": {
      "forced_unsub_tag_mode": "default",
      "virtual_mta": {
        "mode": "select_any"
      },
      "bounce_email": {
        "mode": "select_any"
      },
      "url_domain": {
        "mode": "select_any"
      },
      "email_address": {
        "mode": "select_any"
      },
      "special_sending_rule": {
        "mode": "select_any"
      },
      "remote_database_connection": {
        "mode": "select_any"
      },
      "speed": "select_any",
      "can_edit_header_and_footer": true
    },
    "auto_subscriber_management": {
      "distribute_removals": false,
      "unsub_suppression_list": null,
      "bounce_suppression_list": null,
      "scomp_suppression_list": null
    },
    "sending_quota": {
      "mode": "no_limit"
    },
    "subscriber_quota": {
      "mode": "no_limit"
    }
  },
  "error_code": null,
  "error_message": null
}

Create an Organization

URL

POST /ga/api/v2/organizations

Payload

You should send a JSON object using the Organization Attributes as defined above. No id field is needed for creating a new organization.

Response

The response is a JSON object that is an Organization Object containing details about the new organization.

Example

POST /ga/api/v2/organizations


{
  "organization": {
    "name": "Org",
    "time_zone_name": "(GMT-11:00) American Samoa",
    "permissions": {
      "forced_unsub_tag_mode": "default",
      "virtual_mta": {
        "mode": "select_some",
        "virtual_mtas": [
          {
            "id": 41
          },
          {
            "name": "ipaddr-2"
          },
          {
            "id": 46
          },
          {
            "name": "relay-1"
          }
        ]
      },
      "bounce_email": {
        "mode": "hide_one",
        "bounce_email": {
          "id": "10@12"
        }
      },
      "url_domain": {
        "mode": "hide_one",
        "url_domain": {
          "id": 31
        }
      }
    },
    "sending_quota": {
      "mode": "visible_limit",
      "limit": 5000,
      "overage": 20,
      "notify_organization_admins": false
    },
    "subscriber_quota": {
      "mode": "visible_limit",
      "limit": 5000,
      "overage": 20,
      "notify_organization_admins": true
    },
    "auto_subscriber_management": {
      "distribute_removals": true,
      "bounce_suppression_list": null,
      "scomp_suppression_list": null,
      "unsub_suppression_list": null
    }
  }
}


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "id": 14,
    "name": "Org",
    "anniversary_day": 1,
    "time_zone_name": "(GMT-11:00) American Samoa",
    "time_zone_utc_offset": -39600,
    "active": true,
    "html_header": "",
    "html_footer": "",
    "text_header": "",
    "text_footer": "",
    "custom_headers": "",
    "permissions": {
      "forced_unsub_tag_mode": "default",
      "virtual_mta": {
        "mode": "select_some",
        "virtual_mtas": [
          {
            "id": 41,
            "name": "ipaddr-1",
            "type": "ip_address"
          },
          {
            "id": 42,
            "name": "ipaddr-2",
            "type": "ip_address"
          },
          {
            "id": 44,
            "name": "relay-1",
            "type": "relay_server"
          },
          {
            "id": 46,
            "name": "route-1",
            "type": "routing_rule"
          }
        ]
      },
      "bounce_email": {
        "mode": "hide_one",
        "bounce_email": {
          "id": "10@12",
          "email": "[email protected]"
        }
      },
      "url_domain": {
        "mode": "hide_one",
        "url_domain": {
          "id": 31,
          "domain": "website.example.com"
        }
      },
      "email_address": {
        "mode": "select_any"
      },
      "special_sending_rule": {
        "mode": "none"
      },
      "remote_database_connection": {
        "mode": "none"
      },
      "speed": "select_any",
      "can_edit_header_and_footer": true
    },
    "auto_subscriber_management": {
      "distribute_removals": true,
      "unsub_suppression_list": null,
      "bounce_suppression_list": null,
      "scomp_suppression_list": null
    },
    "sending_quota": {
      "mode": "visible_limit",
      "limit": 5000,
      "overage": 20,
      "notify_organization_admins": false
    },
    "subscriber_quota": {
      "mode": "visible_limit",
      "limit": 5000,
      "overage": 20,
      "notify_organization_admins": true
    }
  },
  "error_code": null,
  "error_message": null
}

Update an Organization

URL

PUT /ga/api/v2/organizations/:organization_id

Payload

You should send a JSON object using the Organization Attributes as defined above. No id field is needed in the JSON object itself, as it is specified on the URL.

Response

The response is a JSON object that is an Organization Object containing details about the updated organization.

Example

PUT /ga/api/v2/organizations/1


{
  "organization": {
    "name": "New Organization Name",
    "anniversary_day": 17,
    "time_zone_name": "(GMT-06:00) Central Time (US & Canada)",
    "active": true,
    "html_header": "<h1>HTML Header</h1>",
    "html_footer": "<h2>HTML Footer</h2>",
    "text_header": "Text Header\n\n",
    "text_footer": "\n\nText Footer\n",
    "custom_headers": "X-ListInfo: My list\nX-Secondary: Other data\n",
    "permissions": {
      "forced_unsub_tag_mode": "default",
      "virtual_mta": {
        "mode": "select_any"
      },
      "bounce_email": {
        "mode": "select_any"
      },
      "url_domain": {
        "mode": "select_any"
      },
      "email_address": {
        "mode": "select_any"
      },
      "special_sending_rule": {
        "mode": "select_any"
      },
      "remote_database_connection": {
        "mode": "none"
      },
      "speed": "select_any",
      "can_edit_header_and_footer": true
    },
    "auto_subscriber_management": {
      "distribute_removals": false,
      "unsub_suppression_list": null,
      "bounce_suppression_list": null,
      "scomp_suppression_list": null
    },
    "sending_quota": {
      "mode": "no_limit",
      "notify_organization_admins": true
    },
    "subscriber_quota": {
      "mode": "no_limit"
    }
  }
}


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "id": 1,
    "name": "New Organization Name",
    "anniversary_day": 17,
    "time_zone_name": "(GMT-06:00) Central Time (US & Canada)",
    "time_zone_utc_offset": -21600,
    "active": true,
    "html_header": "<h1>HTML Header</h1>",
    "html_footer": "<h2>HTML Footer</h2>",
    "text_header": "Text Header\n\n",
    "text_footer": "\n\nText Footer\n",
    "custom_headers": "X-ListInfo: My list\nX-Secondary: Other data\n",
    "permissions": {
      "forced_unsub_tag_mode": "default",
      "virtual_mta": {
        "mode": "select_any"
      },
      "bounce_email": {
        "mode": "select_any"
      },
      "url_domain": {
        "mode": "select_any"
      },
      "email_address": {
        "mode": "select_any"
      },
      "special_sending_rule": {
        "mode": "select_any"
      },
      "remote_database_connection": {
        "mode": "none"
      },
      "speed": "select_any",
      "can_edit_header_and_footer": true
    },
    "auto_subscriber_management": {
      "distribute_removals": false,
      "unsub_suppression_list": null,
      "bounce_suppression_list": null,
      "scomp_suppression_list": null
    },
    "sending_quota": {
      "mode": "no_limit"
    },
    "subscriber_quota": {
      "mode": "no_limit"
    }
  },
  "error_code": null,
  "error_message": null
}

Get an Accounting of Messages Sent by an Organization

This endpoint will return a report on the number of messages sent, broken down by autoresponder and campaign, for a single organization over a time period. It can group by day or by month, returning JSON or CSV data.

URL

GET /ga/api/v2/organizations/:organization_id/messages_sent/daily
GET /ga/api/v2/organizations/:organization_id/messages_sent/daily.csv
GET /ga/api/v2/organizations/:organization_id/messages_sent/monthly
GET /ga/api/v2/organizations/:organization_id/messages_sent/monthly.csv

Parameters

The following parameters may be provided:

start_date

date

The earliest date to include in the report (e.g. 2015-04-01). Defaults to capture three months – so if today is April 1, the default start date is January 1. For monthly reports, the specified value is translated into “the beginning of the specified month”. The “beginning of the month” is the 1st, not the organization’s anniversary.
end_date

date

The latest date to include in the report (e.g. 2015-04-30). Defaults to the end of the current month – so if today is April 2, the default date is April 30. For monthly reports, the specified value is translated into “the end of the specified month”. The “end of the month” is the last day of the calendar month, not the organization’s anniversary.

Response

If the request is made using one of the .csv variations, a CSV document is sent.

The standard JSON response will contain the following fields.

report

array of hashes
time_period_start

string

The earliest time covered by this entry. If a campaign or autoresponder sent over the course of multiple days, it will have multiple entries.
time_period_end

string

The latest time covered by this entry.
campaign_id

integer

The primary key of the campaign that sent this group of messages.
campaign_name

string

The name of the campaign that sent this group of messages.
autoresponder_id

integer

The primary key of the autoresponder that sent this group of messages.
autoresponder_name

string

The name of the autoresponder that sent this group of messages.
messages_sent

integer

The number of messages sent by this object in the specified unit of time.

Example

Example request and JSON response:

> GET /ga/api/organizations/1/messages_sent/daily HTTP/1.1
> Authorization: Basic MToyYjBmNTA5YjQ3MDk1ODk0Mzk5ZWRkMGVhODE1ZDlkMjQ4MzUwYjc4
> Accept: application/json
> Content-Type: application/json


< Content-Type: application/json; charset=utf-8
< X-UA-Compatible: IE=Edge
< ETag: "23895f5c12a983d01679df3d12d35c2e"
< Cache-Control: max-age=0, private, must-revalidate
< Set-Cookie: _session_id=2929b9a1608dab85705f340621b08b30; path=/; HttpOnly
< X-Request-Id: b30346c963612c5e98dab3b438e82dc5
< X-Runtime: 0.056364
< Connection: close
< Server: thin


{
  "success": true,
  "data": {
    "report": [
      {
        "time_period_start": "2015-09-04T00:00:00-05:00",
        "time_period_end": "2015-09-04T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 11,
        "campaign_name": "Default Campaign (Duplicate #10)",
        "messages_sent": 425
      },
      {
        "time_period_start": "2015-09-04T00:00:00-05:00",
        "time_period_end": "2015-09-04T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 13,
        "campaign_name": "Default Campaign (Duplicate #11)",
        "messages_sent": 98
      },
      {
        "time_period_start": "2015-09-05T00:00:00-05:00",
        "time_period_end": "2015-09-05T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 33,
        "campaign_name": "2015-09-05 18:54:07 -0500 (1)",
        "messages_sent": 22
      },
      {
        "time_period_start": "2015-09-05T00:00:00-05:00",
        "time_period_end": "2015-09-05T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 36,
        "campaign_name": "2015-09-05 18:54:07 -0500 (1) (Duplicate #1)",
        "messages_sent": 13078
      },
      {
        "time_period_start": "2015-09-05T00:00:00-05:00",
        "time_period_end": "2015-09-05T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 34,
        "campaign_name": "2015-09-05 18:57:03 -0500 (1)",
        "messages_sent": 4
      },
      {
        "time_period_start": "2015-09-05T00:00:00-05:00",
        "time_period_end": "2015-09-05T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 35,
        "campaign_name": "2015-09-05 18:57:11 -0500 (1)",
        "messages_sent": 4
      },
      {
        "time_period_start": "2015-09-05T00:00:00-05:00",
        "time_period_end": "2015-09-05T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 37,
        "campaign_name": "2015-09-05 19:00:02 -0500 (1)",
        "messages_sent": 19
      },
      {
        "time_period_start": "2015-09-08T00:00:00-05:00",
        "time_period_end": "2015-09-08T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 31,
        "campaign_name": "2015-09-05 18:40:58 -0500 (1)",
        "messages_sent": 24
      },
      {
        "time_period_start": "2015-09-08T00:00:00-05:00",
        "time_period_end": "2015-09-08T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 32,
        "campaign_name": "2015-09-05 18:47:52 -0500 (1)",
        "messages_sent": 4
      },
      {
        "time_period_start": "2015-09-08T00:00:00-05:00",
        "time_period_end": "2015-09-08T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 111,
        "campaign_name": "2015-09-08 08:57:38 -0500 (1)",
        "messages_sent": 24589
      },
      {
        "time_period_start": "2015-09-08T00:00:00-05:00",
        "time_period_end": "2015-09-08T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 112,
        "campaign_name": "2015-09-08 08:57:38 -0500 (2)",
        "messages_sent": 24576
      },
      {
        "time_period_start": "2015-10-15T00:00:00-05:00",
        "time_period_end": "2015-10-15T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 179,
        "campaign_name": "campaign one (Duplicate #9)",
        "messages_sent": 1
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 195,
        "campaign_name": "2015-10-20 13:39:37 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 196,
        "campaign_name": "2015-10-20 13:40:12 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 197,
        "campaign_name": "2015-10-20 13:40:34 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 198,
        "campaign_name": "2015-10-20 13:40:51 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 200,
        "campaign_name": "2015-10-20 13:41:38 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 201,
        "campaign_name": "2015-10-20 13:41:58 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 202,
        "campaign_name": "2015-10-20 13:42:43 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 204,
        "campaign_name": "2015-10-20 13:46:34 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 205,
        "campaign_name": "2015-10-20 13:47:10 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 206,
        "campaign_name": "2015-10-20 13:49:45 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 207,
        "campaign_name": "2015-10-20 13:50:07 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 208,
        "campaign_name": "2015-10-20 13:54:37 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 209,
        "campaign_name": "2015-10-20 13:56:20 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 210,
        "campaign_name": "2015-10-20 13:58:06 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 211,
        "campaign_name": "2015-10-20 13:58:39 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 212,
        "campaign_name": "2015-10-20 13:59:09 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 214,
        "campaign_name": "2015-10-20 14:07:54 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 215,
        "campaign_name": "2015-10-20 14:09:23 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 216,
        "campaign_name": "2015-10-20 14:10:15 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 217,
        "campaign_name": "2015-10-20 14:11:23 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 218,
        "campaign_name": "2015-10-20 14:23:18 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 219,
        "campaign_name": "2015-10-20 14:29:07 -0500 (1)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-10-20T00:00:00-05:00",
        "time_period_end": "2015-10-20T23:59:59-05:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 192,
        "campaign_name": "campaign one (Duplicate #22)",
        "messages_sent": 2
      },
      {
        "time_period_start": "2015-11-06T00:00:00-06:00",
        "time_period_end": "2015-11-06T23:59:59-06:00",
        "autoresponder_id": null,
        "autoresponder_name": null,
        "campaign_id": 228,
        "campaign_name": "one campaign (Duplicate #2)",
        "messages_sent": 1
      }
    ]
  },
  "error_code": null,
  "error_message": null
}

Example CSV response:

"Time Period Start","Time Period End","Organization ID","Organization Name","Campaign ID","Campaign Name","Autoresponder ID","Autoresponder Name","Messages Sent"
"2015-09-04T00:00:00-05:00","2015-09-04T23:59:59-05:00","","","11","Default Campaign (Duplicate #10)","","","425"
"2015-09-04T00:00:00-05:00","2015-09-04T23:59:59-05:00","","","13","Default Campaign (Duplicate #11)","","","98"
"2015-09-05T00:00:00-05:00","2015-09-05T23:59:59-05:00","","","33","2015-09-05 18:54:07 -0500 (1)","","","22"
"2015-09-05T00:00:00-05:00","2015-09-05T23:59:59-05:00","","","36","2015-09-05 18:54:07 -0500 (1) (Duplicate #1)","","","13078"
"2015-09-05T00:00:00-05:00","2015-09-05T23:59:59-05:00","","","34","2015-09-05 18:57:03 -0500 (1)","","","4"
"2015-09-05T00:00:00-05:00","2015-09-05T23:59:59-05:00","","","35","2015-09-05 18:57:11 -0500 (1)","","","4"
"2015-09-05T00:00:00-05:00","2015-09-05T23:59:59-05:00","","","37","2015-09-05 19:00:02 -0500 (1)","","","19"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","31","2015-09-05 18:40:58 -0500 (1)","","","24"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","32","2015-09-05 18:47:52 -0500 (1)","","","4"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","111","2015-09-08 08:57:38 -0500 (1)","","","24589"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","112","2015-09-08 08:57:38 -0500 (2)","","","24576"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","113","2015-09-08 08:57:38 -0500 (3)","","","24648"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","114","2015-09-08 08:57:38 -0500 (4)","","","24019"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","115","2015-09-08 08:57:38 -0500 (5)","","","24870"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","135","2015-09-08 09:16:36 -0500 (1)","","","34008"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","136","2015-09-08 09:16:36 -0500 (2)","","","33936"
"2015-09-08T00:00:00-05:00","2015-09-08T23:59:59-05:00","","","137","2015-09-08 09:16:36 -0500 (3)","","","34046"
"2015-09-09T00:00:00-05:00","2015-09-09T23:59:59-05:00","","","150","2015-09-05 18:40:58 -0500 (1) (Duplicate #1)","","","3612"
"2015-10-30T00:00:00-05:00","2015-10-30T23:59:59-05:00","","","221","hello world (Duplicate #2)","","","4"
"2015-10-30T00:00:00-05:00","2015-10-30T23:59:59-05:00","","","222","hello world (Duplicate #3)","","","4"
"2015-10-30T00:00:00-05:00","2015-10-30T23:59:59-05:00","","","223","hello world (Duplicate #4)","","","4"
"2015-11-03T00:00:00-06:00","2015-11-03T23:59:59-06:00","","","224","hello world (Duplicate #5)","","","4"
"2015-11-06T00:00:00-06:00","2015-11-06T23:59:59-06:00","","","226","one campaign","","","1"
"2015-11-06T00:00:00-06:00","2015-11-06T23:59:59-06:00","","","227","one campaign (Duplicate #1)","","","1"
"2015-11-06T00:00:00-06:00","2015-11-06T23:59:59-06:00","","","228","one campaign (Duplicate #2)","","","1"

Delete an Organization

Only system administrators can delete organizations.

Deleting an organization is a two-step process:

  1. Request a Delete Confirmation Code. This will generate a confirmation code that is valid for 2 minutes.
  2. Send the confirmation code back to the server.

We do this because deleting an organization is what we consider to be a major event.

From that point forward, the organization will no longer appear in the user interface.

URL

To request the confirmation code:

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

To confirm the deletion and start the deletion process:

DELETE /ga/api/v2/organizations/:organization_id/confirmed/:delete_confirmation_code

Response (Request Confirmation Code)

delete_confirmation_code

The token to send back to the server to confirm deletion of the specified organization.
delete_confirmation_expires_at

The time at which the included token will no longer be valid.

Example

GET /ga/api/v2/organizations/17/delete_confirmation_code


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "delete_confirmation_code": "39ac50e5e6defa9592f9d025fca8f3bbc950ce74:1487784882",
    "delete_confirmation_expires_at": "2017-02-22T17:34:42Z"
  },
  "error_code": null,
  "error_message": null
}

Response (Reply with Confirmation Code, Delete Organization)

An empty successful response to this request indicates that the organization has been marked as deleted and the data cleanup listed above has been done.

Example

DELETE /ga/api/v2/organizations/19/confirmed/cf65e2b4ca7ac958b0e944cd7b7919ba1a639fda:1487784882


HTTP/1.1 200 OK


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

Adjust an Organization’s Sending Credits

Only system administrators can adjust an organization’s sending credits.

An organization must already be configured for fixed_credits sending quota.

URL

Get the organization’s current available sending credits (no payload):

GET /api/v2/organizations/:id/sending_credits

Add additional sending credits:

PUT /api/v2/organizations/:id/add_sending_credits

Remove current sending credits:

PUT /api/v2/organizations/:id/remove_sending_credits

Set a new current available sending credits:

PUT /api/v2/organizations/:id/set_sending_credits

Payload

credits

integer

/

required

The number of credits to use in this update.

Response

sending_credits

hash
lifetime_messages_sent

integer

The total number of messages sent by this organization over all time.
current_credits_available

integer

The current number of credits available for sending from this organization.

Example

PUT /ga/api/v2/organizations/1/add_sending_credits


{
  "credits": 500
}


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "sending_credits": {
      "lifetime_messages_sent": 2,
      "current_credits_available": 508
    }
  },
  "error_code": null,
  "error_message": null
}

 Mailing Lists API
Preview Emails API 

Copyright © 2012–2024 GreenArrow Email