Retrieves all communication credit plans for a specific environment

GET /api/configuration/communication-plans/{environmentId}

Success: 200 OK

Products: Gladstone Admin Areas (ADMIN)
Features: not restricted by feature

Overview

Lists the communication credit allocations held by one environment — the bundles of emails and SMS messages that environment may send. Use it to show what has been allocated and when it runs out.

Two kinds of record appear here: allocations taken from a standard plan, which carry that plan's name and limits, and one-off bundles bought outright, which have no plan behind them and therefore come back with a null planName, audienceLimit and siteLimit. Check planName rather than assuming every entry describes a plan.

These are allocations, not balances. includedEmails and includedSMS are what the environment was given, not what it has left — nothing in this response tells you how much has been used.

By default only active allocations are returned; pass includeInactive=true to see expired and switched-off ones too. Results are ordered newest first by startDate, and an environment with no allocations returns 200 with an empty array. An environment id that does not exist is a 400, not an empty list.

The standard plans an allocation can be based on are listed by Retrieve all default communication credit plans.

Endpoint

GET {base_url}/api/configuration/communication-plans/{environmentId}

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Path parameters

Name	Type	Required	Description
`environmentId`	integer (int32)	Yes	The environment whose allocations you want. It is checked before anything is read: an id that does not exist fails with `400` and `EnvironmentId {environmentId} does not exist.`

Query parameters

Name	Type	Required	Description
`includeInactive`	boolean	No	Whether to include allocations that are switched off or have expired. Defaults to `false`, so by default you see only allocations flagged active. Set it to `true` for a history. It filters on the stored active flag alone, so an allocation whose `expiryDate` has passed but which has not been deactivated is still returned either way — compare `expiryDate` yourself.

Sample request

cURL

curl -X GET '{base_url}/api/configuration/communication-plans/{environmentId}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'

Response fields

Field	Type	Description
`[].id`	integer (int32)	Identifies this allocation to this environment, not the underlying plan. This is the id used when the allocation is updated. Do not confuse it with `planId`.
`[].planId`	integer (int32)	The standard plan this allocation was created from, matching `id` in Retrieve all default communication credit plans. A one-off bundle bought outside any plan has no plan behind it, and its plan-derived fields come back null.
`[].planName`	string	The name of the standard plan behind this allocation, copied from the plan record. `null` for a one-off bundle — this is the most reliable way to tell the two kinds apart.
`[].audienceLimit`	integer (int32)	The plan's cap on audience size, taken from the plan rather than from the allocation. `null` for a one-off bundle, and also `null` on a plan that sets no cap.
`[].siteLimit`	integer (int32)	The plan's cap on the number of sites it covers, taken from the plan. `null` for a one-off bundle, and also `null` on a plan that sets no cap.
`[].isActive`	boolean	Whether the allocation is switched on. Always `true` unless you asked for `includeInactive`. It is a stored flag, independent of `expiryDate`, so an active allocation can still be past its expiry.
`[].startDate`	string (date-time)	When the allocation begins. It is the sort key — results come back newest first — so the first entry is the most recently started allocation, which is usually but not necessarily the current one.
`[].expiryDate`	string (date-time)	When the allocation runs out. `null` where no expiry was set, which means it does not lapse on a date. Expiry does not clear `isActive` by itself, so check both before telling a user their credits are still available.
`[].includedEmails`	integer (int32)	How many emails this allocation granted. It is the amount allocated, not the amount remaining, and it is held on the allocation rather than read from the plan — so it can differ from the plan's headline figure. `0` where none were recorded.
`[].includedSMS`	integer (int32)	How many SMS messages this allocation granted, on the same terms as `includedEmails`: allocated rather than remaining, held on the allocation, and `0` where none were recorded. Note the upper-case `SMS` in the field name.

Sample response

200 OK

[
  {
    "id": 12345,
    "planId": 12345,
    "planName": "string",
    "audienceLimit": 1,
    "siteLimit": 1,
    "isActive": true,
    "startDate": "2026-08-14T19:00:00Z",
    "expiryDate": "2026-08-14T19:00:00Z",
    "includedEmails": 1,
    "includedSMS": 1
  }
]

Errors

Status	Meaning	When
`400`	Bad request	No environment exists with the id you supplied. The body is the plain string `EnvironmentId {environmentId} does not exist.` An environment that exists but has no allocations returns `200` with an empty array instead.
`500`	Internal server error	An unexpected server-side failure while reading the allocations, with an empty body.

This page as markdown · All pages · llms.txt