URL: /code/apps/mailboxes · Id: `page:/code/apps/mailboxes`

# Mailboxes

> The addresses your agents send from, warmed, rested and authenticated, with every Suppression and Consent read before each send.

The addresses your agents send from, warmed, rested and authenticated, with every [Suppression](https://startupbuilder.dev/business/nouns/suppression) and [Consent](https://startupbuilder.dev/business/nouns/consent) read before each send.

- **System:** [Mailboxes](https://startupbuilder.dev/systems/mailboxes)
- **Nouns:** 4
- **Verbs:** 9
- **Events:** 9

```text title="Run it · Ask"
Email the launch-day note to my waitlist at 8 a.m. Pacific on November 4.
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Message.broadcast({ message: 'msg_Wl5tQ8nB2r', audience: 'audience_Wt3kP9sL4e', at: '2026-11-04T16:00:00Z' })
```

```json title="Run it · Response"
{
  "api": "https://api.sb/leaseline.app",
  "message": {
    "$id": "https://api.sb/leaseline.app/messages/msg_Wl5tQ8nB2r",
    "$type": "Message",
    "medium": "email",
    "direction": "outbound",
    "from": "dana@leaseline.app",
    "subject": "Leaseline is live on Product Hunt today",
    "purpose": "launch"
  },
  "messages": [
    {
      "$type": "Message",
      "to": "leo@birchline-homes.example",
      "subject": "Leaseline is live on Product Hunt today",
      "body": "Leo, you joined the waitlist in September. Leaseline is live today: rent and every lease renewal tracked in one place, each notice sent 60 days out."
    }
  ],
  "counts": {
    "audience": 640,
    "sending": 611,
    "skippedNoConsent": 21,
    "skippedSuppressed": 8
  },
  "action": {
    "operation": "Message.broadcast",
    "mode": "try",
    "status": "done"
  }
}
```

## Nouns
| Noun | What it is |
| --- | --- |
| [Mailbox](https://startupbuilder.dev/business/nouns/mailbox) | A Mailbox is an email Channel at a Domain, held by a startup, a Role, or a Worker, so every Agent has its own. |
| [Message](https://startupbuilder.dev/business/nouns/message) | A Message is one communication from any party over one medium, such as email, SMS, or chat, inbound or outbound. |
| [Suppression](https://startupbuilder.dev/business/nouns/suppression) | A Suppression is an address a Company never sends commercial Messages to, read before every send from any of its startups. |
| [Consent](https://startupbuilder.dev/business/nouns/consent) | A Consent is a person’s grant for one Purpose, with its basis, region, notice, evidence, and expiry. |

## Properties
The hub defines each Noun’s core Properties; Mailboxes adds the ones a sale needs.

### Mailbox
| Property | Type | What it holds | Defined by |
| --- | --- | --- | --- |
| `address` | `email` | The email address. | The hub |
| `stream` | `string` | What it sends: receipts and resets, broadcasts, or cold outbound; one stream per Mailbox. | The hub |
| `dailyCap` | `integer` | Sends allowed today, raised by the warmup ramp and cut by the brakes. | The hub |
| `status` | `string` | Where the Mailbox stands in its warmup and rest cycle. | The hub |
| `tenant` | `tenant` | The Tenant it sends for, at a Domain that Tenant’s customer holds; replies land in the Tenant’s Threads. | The hub |
| `domain` | `Domain` | Its domain; cold outbound lives only on a second domain, never your primary. | Mailboxes |
| `bounceRate` | `number` | Hard bounces over the last 7 days; over 2% rests the Mailbox. | Mailboxes |
| `spamRate` | `number` | Complaints reported by the inbox providers; over 0.3% rests it. | Mailboxes |

### Message
| Property | Type | What it holds | Defined by |
| --- | --- | --- | --- |
| `medium` | `string` | One of `email`, `sms`, `voice`, or `chat`. | The hub |
| `direction` | `string` | One of `inbound` or `outbound`. | The hub |
| `body` | `text` | What it says. | The hub |
| `from` | `string` | The sender: an address, a number, or a Channel id. | The hub |
| `to` | `string` | The recipient: an address, a number, or a Person id. | The hub |
| `subject` | `string` | The subject line, for email. | The hub |
| `purpose` | `string` | Why it goes out, such as onboarding; consent and suppression rules read it. | The hub |
| `mailbox` | `Mailbox` | The Mailbox it sends from, which sets its daily cap. | Mailboxes |
| `thread` | `string` | The thread it belongs to, so a follow-up lands under the first email. | Mailboxes |

### Suppression
| Property | Type | What it holds | Defined by |
| --- | --- | --- | --- |
| `address` | `string` | The email address or phone number. | The hub |
| `reason` | `string` | Why it is suppressed, such as an opt-out or a bounce. | The hub |

### Consent
| Property | Type | What it holds | Defined by |
| --- | --- | --- | --- |
| `region` | `string` | The jurisdiction whose rules apply. | The hub |
| `withdrawnAt` | `datetime` | When the person withdrew it. | The hub |

## Lifecycle
Every move names the Verb that makes it, or the Event it waits on.

### Mailbox
| State | What it means | Moves to |
| --- | --- | --- |
| `warming` (first) | Its daily sends ramp toward its cap over two to four weeks. | `active` by [`Mailbox.warm`](https://startupbuilder.dev/business/nouns/mailbox/warm); `retired` by [`Mailbox.retire`](https://startupbuilder.dev/business/nouns/mailbox/retire) |
| `active` | It sends up to its cap while its readings stay inside their brakes. | `resting` by [`Mailbox.rest`](https://startupbuilder.dev/business/nouns/mailbox/rest); `retired` by [`Mailbox.retire`](https://startupbuilder.dev/business/nouns/mailbox/retire) |
| `resting` | A brake fired, so it sends nothing until the reading clears. | `active` by [`Mailbox.warm`](https://startupbuilder.dev/business/nouns/mailbox/warm); `retired` by [`Mailbox.retire`](https://startupbuilder.dev/business/nouns/mailbox/retire) |
| `retired` | It sends nothing again; its address, Messages and sending history stay. | None: it ends here. |

## Verbs
| Verb | What it does | Approval | On each site | Limits |
| --- | --- | --- | --- | --- |
| [`Message.schedule`](/code/apps/mailboxes/schedule) | Holds one email until the minute you set, such as 9:10 in the buyer’s morning, then sends it from your Mailbox. | Runs on its own | Gmail, LinkedIn, Outlook, X | Cold first touches send only from a warmed second domain: 2 Mailboxes at 25 a day each after a 14-day ramp, 50 a day in all. Warm intros and replies send from your primary domain. |
| [`Message.broadcast`](/code/apps/mailboxes/broadcast) | Sends one email to a whole Audience, such as your waitlist, now or at a set time. | Goes out on its own | Gmail, Outlook | Only to people who opted in; a broadcast never goes to a cold list. |
| [`Mailbox.warm`](https://startupbuilder.dev/business/nouns/mailbox/warm) | Ramps a new Mailbox from 5 sends a day to 25 over 14 days, before any cold email leaves it. | Runs on its own | None. | Fourteen days from 5 sends a day to 25; no cold email leaves a Mailbox still warming. |
| [`Mailbox.rest`](https://startupbuilder.dev/business/nouns/mailbox/rest) | Pauses a Mailbox’s sending when a brake fires, such as bounces over 2%, and resumes it when the reading clears. | Runs on its own | None. | None. |
| [`Domain.authenticate`](https://startupbuilder.dev/business/nouns/domain/authenticate) | Writes your domain’s SPF, DKIM and DMARC records and checks them before its first send. | Runs on its own | None. | None. |
| [`Mailbox.retire`](https://startupbuilder.dev/business/nouns/mailbox/retire) | Stops a Mailbox for good and keeps its address, Messages and sending history. | Runs on its own | None. | None. |
| [`Contact.suppress`](https://startupbuilder.dev/business/nouns/contact/suppress) | Adds an address to the one list every send reads first, honored by every startup, forever. | Runs on its own | None. | None. |
| [`Contact.unsubscribe`](https://startupbuilder.dev/business/nouns/contact/unsubscribe) | Stops commercial email to a person in one click, for one topic or all, at once. | Runs on its own | Gmail, Outlook | None. |
| [`Consent.withdraw`](https://startupbuilder.dev/business/nouns/consent/withdraw) | Ends a Consent at once: sending for its purpose stops, and the record stays. | Runs on its own | None. | None. |

## Events
| Event | Emitted by |
| --- | --- |
| `Message.scheduled` | [`Message.schedule`](/code/apps/mailboxes/schedule) |
| `Message.broadcasted` | [`Message.broadcast`](/code/apps/mailboxes/broadcast) |
| `Mailbox.warmed` | [`Mailbox.warm`](https://startupbuilder.dev/business/nouns/mailbox/warm) |
| `Mailbox.rested` | [`Mailbox.rest`](https://startupbuilder.dev/business/nouns/mailbox/rest) |
| `Mailbox.retired` | [`Mailbox.retire`](https://startupbuilder.dev/business/nouns/mailbox/retire) |
| `Domain.authenticated` | [`Domain.authenticate`](https://startupbuilder.dev/business/nouns/domain/authenticate) |
| `Contact.suppressed` | [`Contact.suppress`](https://startupbuilder.dev/business/nouns/contact/suppress) |
| `Contact.unsubscribed` | [`Contact.unsubscribe`](https://startupbuilder.dev/business/nouns/contact/unsubscribe) |
| `Consent.withdrawn` | [`Consent.withdraw`](https://startupbuilder.dev/business/nouns/consent/withdraw) |

A [Trigger](https://startupbuilder.dev/business/nouns/trigger) can start a Workflow on any of them, and a Watch delivers each to your endpoint, signed ([Events and webhooks](/code/events)).

## Who operates it
| Part | Mailboxes |
| --- | --- |
| Accountable | [Prospector](https://startupbuilder.dev/agents/sales/prospector) |
| Also calls its Verbs | [Customer lead](https://startupbuilder.dev/agents/customer/customer-lead), [Marketing lead](https://startupbuilder.dev/agents/marketing/marketing-lead), [Onboarding Specialist](https://startupbuilder.dev/agents/customer/onboarding-specialist), [Billing Specialist](https://startupbuilder.dev/agents/finance/billing-specialist), [Success Manager](https://startupbuilder.dev/agents/customer/success-manager), [Partner Manager](https://startupbuilder.dev/agents/sales/partner-manager) |
| Seat | An agent holds each seat until you seat a person in it. |
| Asks you first | None of its Verbs: each runs within its seat’s Limits |

## Integrations
[Gmail](/code/integrations/gmail) · [Outlook](/code/integrations/outlook)

## Import and export
| Direction | What | How |
| --- | --- | --- |
| Import | Your existing inbox and its threads | `Integration.connect` for [Gmail](/code/integrations/gmail) or [Outlook](/code/integrations/outlook); replies land in the thread they answer |
| Import | Your Suppressions from another tool | `Contact.suppress` for each address; suppressions are never removed |
| Export | Every Message, with its reply and outcome | `Collection.export` |

## Example
**A second domain, warmed before the first cold email.**

1. `Domain.authenticate` writes SPF, DKIM and DMARC for tryleaseline.app and checks each one.
2. `Mailbox.warm` ramps dana@tryleaseline.app and ops@tryleaseline.app from 5 a day to 25 over 14 days.
3. On day 15, `Message.schedule` holds each first touch for 9:10 in the buyer’s time zone: 50 a day across the two.
4. A bounce spike past 2% on one Mailbox fires its brake; `Mailbox.rest` pauses it until the reading clears.