Send Plan (billing)

Request

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

const response = await fetch('https://app.mailyte.com/api/v1/billing/send-plan', {
  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/send-plan",
    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/send-plan');

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

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/billing/send-plan")
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) }

Response

Success.

• dataobject

  The Send plan held, this month's overage, and the spend cap. No payment processor is named: which rail would collect an overage charge is our arrangement, not the customer's data.

  • objectstringsend_plan
  • plan_keystring

    The catalogue key of the plan held. **null means NONE — this organization is on no Send plan at all**, which is a real and common state rather than a gap in what we read. Plans are mutually exclusive by design, so there is never more than one.

  • currencystring

    ISO 4217 code, e.g. `NGN` or `USD`. Every amount below is in this currency's minor unit, unconverted. IT IS ALWAYS POPULATED: it is taken from the live subscription when there is one, and falls back to `NGN` — the currency the price list is written in — when there is not. So null does NOT mean "no plan" (that is `plan_key`) and does NOT mean "no overage rate exists" (that is `overage.rate_per_thousand`): an organization with neither still reads `NGN` here. **null means UNKNOWN — the currency was not supplied**, and in that case NO amount in this response can be interpreted at all, since every one of them is a count of this currency's minor units. Treat the amounts as unreadable rather than assuming a default.

  • included_monthlyinteger

    Emails a month the plan includes. Computed from the catalogue on our side, so this is the one figure here an unreachable mail server cannot make unknown, and it does not go null with the meters below. An organization on no plan reads `0`. **null means UNKNOWN — the figure was not supplied**, never zero.

  • used_this_monthinteger

    Emails sent this calendar month, per the mail server. **null means UNKNOWN — the meter could not be read.** It never means zero. Only one of those two says the integration is idle, and treating unknown as zero is how a customer is under-billed silently. Retry rather than conclude anything. THE FOUR FIELDS DERIVED FROM THIS ONE GO NULL WITH IT: `overage.emails`, `overage.amount` and `spend_cap.reached`.

  • overageobject

    Sending past `included_monthly`, and what it costs.

    • emailsinteger

      Emails past the included volume. **null means UNKNOWN — the meter this is derived from could not be read at the mail server**, in exactly the cases `used_this_month` is null: a derived number is as unknown as what it came from. Never zero; retry rather than conclude the customer is inside their allowance.

    • amountinteger

      What the overage costs so far this month. Integer in the MINOR UNITS of `currency` — kobo when `currency` is `NGN`, cents when it is `USD`. Never a major-unit or decimal value: `150000` under `NGN` is ₦1,500.00, not ₦150,000. **null means UNKNOWN**, whenever `used_this_month` is null. It is NOT a zero bill: a zero here derived from an unread meter is the under-billing this field exists to refuse.

    • rate_per_thousandinteger

      Charged per 1,000 emails past the included volume. Integer in the MINOR UNITS of `currency` — kobo when `currency` is `NGN`, cents when it is `USD`. Never a major-unit or decimal value: `150000` under `NGN` is ₦1,500.00, not ₦150,000. **null means NONE — the plan has no overage rate** — a real setting, not an unread meter. This one comes from the price list, not the mail server, which is why it stays known when the meters do not.

  • spend_capobject

    An optional ceiling on overage spend for the month.

    • amountinteger

      The cap. Integer in the MINOR UNITS of `currency` — kobo when `currency` is `NGN`, cents when it is `USD`. Never a major-unit or decimal value: `150000` under `NGN` is ₦1,500.00, not ₦150,000. **null means NONE — NO CAP is set.** This comes from our own table and is never unreadable. **`0` IS A REAL AND DIFFERENT SETTING**, meaning "stop at my included volume, never charge me overage". Do not collapse the two: a cap is cleared by sending null, never by sending zero, and reading a `0` as "no cap" would let an account that asked never to be charged run up a bill.

    • reachedboolean

      Whether the cap has been hit. **null means UNKNOWN** — there is a cap, but the overage it would be compared against rests on a meter the mail server could not give us, so it could not be measured. `false` here is a positive claim that the cap has NOT been reached, and is the more dangerous of the two wrong answers: it would let a client sail past a cap it believed unreached. `false` is also the honest answer when `amount` is null, since no cap can be reached.

    • ceiling_emailsinteger

      The cap expressed in emails — the only unit the mail server can enforce on the send path, since it counts messages and cannot evaluate a money figure. **null means NONE — no ceiling**, which follows from `spend_cap.amount` being null; it is derived from the cap and the rate on our side, so it is never unknown.

Returned inside the standard envelope.

Errors

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