Entitlements (billing)

GET/api/v1/billing/entitlements

Requires anorganization API keywith the scopeaccount:read

Request

GET/api/v1/billing/entitlements

curl -X GET 'https://app.mailyte.com/api/v1/billing/entitlements' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY'

const response = await fetch('https://app.mailyte.com/api/v1/billing/entitlements', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
  },
});
const { data } = await response.json();

import requests
response = requests.get(
    "https://app.mailyte.com/api/v1/billing/entitlements",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->get('https://app.mailyte.com/api/v1/billing/entitlements');

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/billing/entitlements")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

The key names its own organization, so no X-Organization-ID header is needed.

Response

Success.

dataobject
- objectstringentitlements
- planobject
  What has been bought. Replaces four rival booleans (`has_subscription`, `has_paid_seats`, `has_paid_product`, `has_send_plan`) that answered one question from four angles and gave a caller four chances to read the wrong one.
  - tierstringfree | paid
    The honest summary of whether anything has been bought. It is also what the mail server holds this organization's bounce tripwires to. `free` and `paid` are the whole set and EVERY organization has one: an organization that has bought nothing reads `free`, not null. So **null means UNKNOWN — the entitlement snapshot did not carry the field** — and must not be read as "no plan". "No plan" is `tier: "free"` with `status: null` beside it, and those two together are the answer `has_subscription` and three other booleans used to give four ways.
  - statusstringpending | active | past_due | suspended | cancelled
    **null means NONE — there is no subscription at all.** It is the one flag that replaced `has_subscription`, an answer rather than a missing value, and it is why four rival booleans could be dropped.
- seatsobject
  Paid seats bought and in use, per tier. What a null on any leaf below means is stated ON THAT LEAF — this heading does not reach the field you are indexing into, and a caller reads the field it is using.
  - standardobject
    Seats of the standard tier. Both figures come from the entitlement snapshot, which counts them locally.
    - ownedinteger
      Seats bought at this tier. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
    - assignedinteger
      Seats in use. Can exceed `owned` after a downgrade. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
  - proobject
    Seats of the pro tier. Both figures come from the entitlement snapshot, which counts them locally.
    - ownedinteger
      Seats bought at this tier. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
    - assignedinteger
      Seats in use. Can exceed `owned` after a downgrade. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
  - workplaceobject
    Seats of the workplace tier. Both figures come from the entitlement snapshot, which counts them locally.
    - ownedinteger
      Seats bought at this tier. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
    - assignedinteger
      Seats in use. Can exceed `owned` after a downgrade. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
- mailbox_tiersobject
  What each tier grants one mailbox, free included, so a caller sizing an integration can see what the tier they are about to buy gives. NULL DOES NOT MEAN THE SAME THING ON ALL THREE FIELDS: on `daily_send_limit` it means NO LIMIT, a real entitlement; on `storage_bytes` and `assistant_actions` it means UNKNOWN, because those are finite grants and an unlimited reading would be an invention. Each leaf says which — read the leaf, not this heading.
  - freeobject
    What the free tier grants ONE mailbox.
    - storage_bytesinteger
      Bytes — the same unit as every other size in the API, never GB. **null means UNKNOWN — the catalogue figure was not readable.** Unlike `daily_send_limit` below it, this one has no "no limit" reading: every tier has a finite mailbox quota, so a null here is a gap in what we were given rather than an unlimited allowance.
    - daily_send_limitinteger
      Emails one mailbox of this tier may send per day. **null means NO LIMIT, not unknown.** A `0` is never published here: the stored column uses 0 for "uncapped" (the rate limiter enforces only on `daily_limit > 0`), and publishing that 0 verbatim would tell a caller their most expensive tier may send nothing at all. Any new-account clamp is already applied to this number, so what you see is what binds.
    - assistant_actionsinteger
      Assistant actions granted per mailbox, per month. A tier that grants none reads `0`, and THAT `0` MEANS NONE — not "uncapped", which is what a 0 means two lines above in `daily_send_limit`. The two conventions sit in one object, so read each field's own note. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
  - standardobject
    What the standard tier grants ONE mailbox.
    - storage_bytesinteger
      Bytes — the same unit as every other size in the API, never GB. **null means UNKNOWN — the catalogue figure was not readable.** Unlike `daily_send_limit` below it, this one has no "no limit" reading: every tier has a finite mailbox quota, so a null here is a gap in what we were given rather than an unlimited allowance.
    - daily_send_limitinteger
      Emails one mailbox of this tier may send per day. **null means NO LIMIT, not unknown.** A `0` is never published here: the stored column uses 0 for "uncapped" (the rate limiter enforces only on `daily_limit > 0`), and publishing that 0 verbatim would tell a caller their most expensive tier may send nothing at all. Any new-account clamp is already applied to this number, so what you see is what binds.
    - assistant_actionsinteger
      Assistant actions granted per mailbox, per month. A tier that grants none reads `0`, and THAT `0` MEANS NONE — not "uncapped", which is what a 0 means two lines above in `daily_send_limit`. The two conventions sit in one object, so read each field's own note. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
  - proobject
    What the pro tier grants ONE mailbox.
    - storage_bytesinteger
      Bytes — the same unit as every other size in the API, never GB. **null means UNKNOWN — the catalogue figure was not readable.** Unlike `daily_send_limit` below it, this one has no "no limit" reading: every tier has a finite mailbox quota, so a null here is a gap in what we were given rather than an unlimited allowance.
    - daily_send_limitinteger
      Emails one mailbox of this tier may send per day. **null means NO LIMIT, not unknown.** A `0` is never published here: the stored column uses 0 for "uncapped" (the rate limiter enforces only on `daily_limit > 0`), and publishing that 0 verbatim would tell a caller their most expensive tier may send nothing at all. Any new-account clamp is already applied to this number, so what you see is what binds.
    - assistant_actionsinteger
      Assistant actions granted per mailbox, per month. A tier that grants none reads `0`, and THAT `0` MEANS NONE — not "uncapped", which is what a 0 means two lines above in `daily_send_limit`. The two conventions sit in one object, so read each field's own note. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
  - workplaceobject
    What the workplace tier grants ONE mailbox.
    - storage_bytesinteger
      Bytes — the same unit as every other size in the API, never GB. **null means UNKNOWN — the catalogue figure was not readable.** Unlike `daily_send_limit` below it, this one has no "no limit" reading: every tier has a finite mailbox quota, so a null here is a gap in what we were given rather than an unlimited allowance.
    - daily_send_limitinteger
      Emails one mailbox of this tier may send per day. **null means NO LIMIT, not unknown.** A `0` is never published here: the stored column uses 0 for "uncapped" (the rate limiter enforces only on `daily_limit > 0`), and publishing that 0 verbatim would tell a caller their most expensive tier may send nothing at all. Any new-account clamp is already applied to this number, so what you see is what binds.
    - assistant_actionsinteger
      Assistant actions granted per mailbox, per month. A tier that grants none reads `0`, and THAT `0` MEANS NONE — not "uncapped", which is what a 0 means two lines above in `daily_send_limit`. The two conventions sit in one object, so read each field's own note. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
- limitsobject
  Account-wide ceilings. **null means NO LIMIT, not unknown** — that is precisely what the entitlement returns for a paying organization, and this publishes its meaning rather than flattening it to a number.
  - max_mailboxesinteger
    Mailboxes this organization may hold in total. **null means NO LIMIT, not unknown.**
  - max_domainsinteger
    Domains this organization may add. **null means NO LIMIT, not unknown.**
  - max_aliases_per_mailboxinteger
    Aliases each mailbox may have. **null means NO LIMIT, not unknown.**
  - max_team_membersinteger
    People who may be invited to the organization. **null means NO LIMIT, not unknown.**
- allowancesobject
  - app_send_monthlyinteger
    Emails a month from a Send plan plus any seats held. Computed from the catalogue, never fetched, so an unreachable mail server cannot make it unknown. An organization holding no monthly volume reads `0`. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed. There is deliberately NO daily figure on this endpoint: what is enforced daily is published once, by `GET /billing/usage`.
  - send_credit_balanceinteger
    The LEDGER balance of send credits — a count of emails, not money. This is the accounting figure; a caller deciding whether it can send right now should read `GET /billing/usage`, which publishes the enforcer's live counter and says which source answered. An account that holds no credits reads `0`. **null means UNKNOWN — the entitlement snapshot did not carry this figure.** It is never zero: an organization with none of this reads `0`, and this resource refuses to cast a missing figure to 0 rather than publish a number nobody computed.
- featuresobject
  Feature entitlements. Whether a feature is GRANTED, not whether it is configured.
  - branded_webmailboolean
  - priority_supportboolean
  - dedicated_ipboolean
    Whether a dedicated IP may be requested. Its state is at `GET /dedicated-ip`.

Returned inside the standard envelope.

Errors

Status	When
`401`	The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.
`403`	The key is valid but may not do this: it lacks the required scope, its IP allowlist does not include you, or this endpoint does not accept API keys.
`404`	No such resource in this organization.
`422`	The request was understood but the values were not acceptable.
`429`	Too many requests, or the organization has spent its sending allowance. `Retry-After` says how long to wait.

Every status, with what causes it and what to do, is on the error reference.