Sub-account billing emails not arriving: a triage runbook

Rate-sheet emails and balance alerts for your sub-accounts are routed by a small set of controls you own: the per-subaccount recipient lists, the white-label sender identity, the DKIM/SPF verification state of that identity, and the organization’s status. When one sub-account’s billing emails stop arriving while everyone else’s keep flowing, one of these controls redirected or paused them. This runbook walks them in the order that diagnoses fastest. If what is missing is an in-app alert rather than an email, see In-dashboard notifications and the Notifications feed. If what is missing is a digest, see the Digest and notification channels FAQ: digests are a separate system and none of the controls below delay or redirect them.

Trigger symptoms

This runbook applies when you see one of these patterns:

The finance inbox never receives rate-sheet emails for one specific sub-account, while the parent organization’s rate sheets still arrive.
Balance-alert emails for a sub-account stop shortly after you changed that sub-account’s alert threshold.
Different sub-accounts show different sender identities: some emails arrive co-branded, others from the platform’s default address.

Each pattern maps to a different control. The decision tree isolates which one.

Decision tree

Walk the four questions in order. Each answer points at the section that fixes it.

Billing email missing for one sub-account?
|
+-- 1. Is a recipient list configured for this sub-account
|      (Settings > Sub-accounts > [sub-account], or on its parent)?
|      +-- No  -> the email routed to the nearest configured ancestor
|      |        list, then to the platform catch-all. Check the
|      |        catch-all inbox: the email usually arrived somewhere
|      |        nobody reads. See "The four email classes".
|      +-- Yes -> the email went to the configured addresses.
|                 Check suppression (misconfiguration 5).
|
+-- 2. Is a custom from-address set for this sub-account?
|      +-- Yes -> explains sender identity, not missing mail. If
|      |        recipients report spam-filtering, see misconfiguration 1.
|      +-- No  -> sender identity is inherited; not a delivery cause.
|
+-- 3. Is the custom from-address's domain DKIM/SPF verified?
|      +-- No  -> emails send from the fallback sender (parent's
|      |        verified domain, then platform default). Recipients
|      |        who filter unfamiliar senders may discard them.
|      +-- Yes -> sender is active; not a delivery cause.
|
+-- 4. Is the sub-account suspended?
       +-- Yes -> email sends pause while the suspension lasts.
                 See misconfiguration 4.

The four email classes

Four classes of email touch a sub-account, and only the first two follow the billing recipient resolver:

Class	Who receives it	Who it sends from	Where you configure it
Rate sheet emails	Child, then parent, then platform catch-all: the first configured list wins	The effective sender (below)	Sub-account notification recipients
Balance alert emails	Same resolver chain as rate sheets	Same	Same
Sender identity (`from_name` / `from_address`)	Not a recipient control: it sets the From line, not the To line	The sub-account’s own verified domain, else the nearest ancestor’s, else the platform default	Settings > Sub-accounts > [sub-account] > Notification email
Digest notification emails	The digest’s own recipient rules on its own cadence	Its own scheduler	Digest and notification channels FAQ

Rate-sheet and balance-alert emails resolve recipients child to parent to platform: the first tier with a usable list wins, and a cleared list counts as absent. These are the only two categories the recipient lists route; invites, security notifications, digests, and webhook alerts keep their own rules. The sender identity resolves through the same chain shape, gated on verification: a configured from-address activates only once its sending domain passes DKIM/SPF, otherwise resolution falls through to the nearest ancestor with a verified sender, then to the platform default. The API reports which tier won as effective.source: subaccount, ancestor, or platform. Digest emails are separate from billing routing in both directions: changing billing recipients never redirects a digest, and a digest cadence never delays a rate sheet or balance alert.

The six most common misconfigurations

Custom from-address set, sending domain never verified

Symptom. The sub-account’s emails arrive from the platform default address instead of your brand, and some recipients report them as spam. Root cause. A from-address activates only after its domain passes DKIM/SPF. Until then the sender falls back to the parent’s verified sender, then the platform default. The email still sends, just not from the address your recipients expect. Fix. Verify the domain under the Verify console, or clear the from-address to inherit on purpose. The Notification email panel shows a Verified or Pending badge for the configured domain, so you never have to guess.

Recipients set on the parent, then the child moved under a different parent

Symptom. After reorganizing your hierarchy, one child’s billing emails go to the old parent’s finance inbox. Root cause. A child with no list of its own inherits from its current parent. Moving the child changes which list it inherits; nothing about the child itself changed. Fix. If an inbox must survive re-parenting, set the list on the child itself under Sub-account notification recipients.

One malformed address rejected the whole list

Symptom. You saved a recipient list, but emails keep going to the previous inboxes, and reading the list back shows the field as not configured. Root cause. Every entry must be a single clean address. One bad entry, for example a stray space inside john @acme.example, rejects the entire list: Orbit falls back to the previous recipients rather than silently dropping the one address you believe is configured. Fix. Read the list back with GET /subaccounts/:id/notification-recipients, compare it with what you saved, correct or remove the malformed entry, and save again.

The sub-account is suspended

Symptom. Every billing email for one sub-account stops at once, on a date that matches a status change in the console. Root cause. Suspension pauses email sends while it lasts. That is a pause, not a routing misconfiguration: the recipient lists and sender verification stay as they were, and no email setting is broken. Pause holds sends while a status lasts; block is the harder billing stop. Both freeze email while active, and neither is diagnosed from the email settings. Fix. Reinstate the organization from the Subaccounts console; for what pause and block each mean for billing, see Billing pause and block recovery. Do not debug email settings while the organization is suspended.

The recipient inbox is suppression-listed

Symptom. The configuration reads correctly and other recipients receive, but one inbox never does. Root cause. An inbox that hard-bounced or complained in the past is suppression-listed, and sends to it are skipped until the address is removed. Fix. Locate the address on the suppression surface described in Email bounces and complaints and remove it once the mailbox is healthy again.

The missing email is a digest, and its cadence is set to Never

Symptom. A periodic summary email stopped, while rate sheets and balance alerts for the same sub-account still arrive. Root cause. Digests run on a per-channel cadence you control. A channel set to Never produces no digest emails at all, whatever the billing routing says. Fix. Check the digest cadence per channel in the Digest and notification channels FAQ. Billing recipient lists do not gate digests, so a correctly configured rate-sheet list will not bring a disabled digest back.

API sanity check

One read confirms the effective sender configuration for a sub-account:

curl -s https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/notification-email \
  -H "X-API-Key: dv_live_sk_your_parent_key"

{
  "from_name": "Acme Billing",
  "from_address": "billing@acme.example",
  "verified": false,
  "effective": {
    "from_address": "noreply@orbit.devotel.io",
    "from_name": null,
    "source": "platform",
    "resolved_from_organization_id": null
  }
}

Read the two halves as a pair:

from_address and verified are what you configured and whether the domain passed DKIM/SPF.
effective is what resolution actually picked. effective.source names the winning tier: subaccount means your override is live, ancestor means the child inherits a parent’s verified sender, platform means resolution fell through to the default.

When you configured a from-address but effective.source is not subaccount, verification or absence overrode you: the email still sends, from the fallback address. To check recipient routing, read the companion endpoint GET /subaccounts/:id/notification-recipients; a null field there means “inherit from the parent chain”, not “no recipients”.

What this guide does not cover

Recipient-side filtering: corporate or carrier spam filters that discard mail after Orbit handed it over. If effective reads correctly and the inbox is not suppression-listed, check the receiving mailbox’s quarantine.
Marketing campaign send identity: campaigns use the verified-sender surface under the Verify console, not the notification-sender panel.
Webhook failure alerts and other platform emails: they keep their own recipient rules, as described in Sub-account notification recipients.

Reference

Sub-account billing emails not arriving: a triage runbook

Sub-account billing emails not arriving: a triage runbook

Trigger symptoms

Decision tree

The four email classes

The six most common misconfigurations

Custom from-address set, sending domain never verified

Recipients set on the parent, then the child moved under a different parent

One malformed address rejected the whole list

The sub-account is suspended

The recipient inbox is suppression-listed

The missing email is a digest, and its cadence is set to Never

API sanity check

What this guide does not cover

See also

​Sub-account billing emails not arriving: a triage runbook

​Trigger symptoms

​Decision tree

​The four email classes

​The six most common misconfigurations

​Custom from-address set, sending domain never verified

​Recipients set on the parent, then the child moved under a different parent

​One malformed address rejected the whole list

​The sub-account is suspended

​The recipient inbox is suppression-listed

​The missing email is a digest, and its cadence is set to Never

​API sanity check

​What this guide does not cover

​See also

Sub-account billing emails not arriving: a triage runbook

Trigger symptoms

Decision tree

The four email classes

The six most common misconfigurations

Custom from-address set, sending domain never verified

Recipients set on the parent, then the child moved under a different parent

One malformed address rejected the whole list

The sub-account is suspended

The recipient inbox is suppression-listed

The missing email is a digest, and its cadence is set to Never

API sanity check

What this guide does not cover

See also