> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Rate-sheet and balance-alert emails for a sub-account pass through four tenant-owned controls before they reach an inbox: recipient lists, sender identity, domain verification, and organization status. Walk them in order to find which one redirected or paused the email.

# 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](/guides/in-dashboard-notifications) and the [Notifications feed](/guides/notifications-feed). If what is missing is a digest, see the [Digest and notification channels FAQ](/guides/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.

```text theme={null}
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](/guides/subaccounts-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](/guides/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](/guides/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](/guides/subaccounts-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](/guides/subaccounts-console); for what pause and block each mean for billing, see [Billing pause and block recovery](/troubleshooting/billing-pause-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](/troubleshooting/email-bounces-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](/guides/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:

```bash theme={null}
curl -s https://api.orbit.devotel.io/api/v1/subaccounts/sub_abc123/notification-email \
  -H "X-API-Key: dv_live_sk_your_parent_key"
```

```json theme={null}
{
  "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](/guides/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](/guides/subaccounts-notification-recipients).

## See also

* [Sub-account notification recipients](/guides/subaccounts-notification-recipients)
* [White-label subaccounts](/guides/subaccounts-reseller)
* [Subaccounts console](/guides/subaccounts-console)
* [Verify console](/guides/verify-console)
* [Digest and notification channels FAQ](/guides/digest-and-notification-channels-faq)
* [Email bounces and complaints](/troubleshooting/email-bounces-complaints)
* [Email DNS drift](/troubleshooting/email-dns-drift)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.