Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# email-outbound Card

# Authoring Outbound Emails

You compose an email by writing an `email-outbound` card. Headers live
in the YAML frontmatter; the message body is the markdown body of the
card. The Gmail connector picks the card up on the next sync and
creates a Gmail draft for the user to review and send.

## Required fields (frontmatter)

- `to:` — recipient address(es), comma-separated
- `subject:` — subject line. For replies, prefix with `Re:` to match
  the source thread's subject.

The card's body is the email body. Markdown subset only:
`**bold**`, `*italic*`, `[text](url)`. Nothing else.

## Optional fields

- `cc:` and `bcc:` — additional recipients
- `in-reply-to.ref:` — for replies, points at the source
  `email-message` card. Use a path **relative to the draft's
  directory** (typically just `msg-NNN.email-message.card` since the
  draft sits in the same thread directory). The connector reads the
  source card's `message-id` and `thread-id` to set Gmail threading
  headers — if the ref doesn't resolve, the upload fails rather than
  silently lose threading.

## Placement

- **Reply drafts** go inside the existing thread's `.attach/` next to
  the source message, e.g.
  `_content/inbox/email/thread-X.attach/draft-001.email-outbound.card`. This
  keeps the conversation co-located.
- **New emails (no thread)** go in a fresh directory under
  `_content/inbox/email/`.

## Lifecycle

- `status: draft` (default) — the connector uploads to Gmail's Drafts
  folder on next sync and stamps the card with `gmail-draft-id:` and
  `gmail-draft-url:`. Share the URL with the user so they can review
  and send. Once stamped, the draft is **not** re-uploaded; editing
  the card after upload doesn't update the Gmail draft (yet).
- Deleting the card does **not** delete the Gmail draft — once Gmail
  has it, the user owns it.

## Threading checklist for replies

1. Place the draft in the **same directory** as the source message.
2. Set `in-reply-to.ref:` pointing at the specific message you're
   replying to.
3. Set `subject: Re: <original subject>`.
4. Don't set `status` explicitly — it defaults to `draft`.

## The `contains:` field

Give this card a one-sentence `contains:` — the prime retrieval field for
`bbx search` and listings. How to write a good one (carry the information when
it's concise, never a list of parts, under 200 characters) is in the agent
guide's ABOUT_CARDS section.