Skip to content

fix(skill): document bundle postings and topic ID resolution #157

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joshRpowell wants to merge 2 commits into
base: main
Choose a base branch
from
Open

fix(skill): document bundle postings and topic ID resolution #157

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cabcf0
fix(skill): clarify box topic IDs
joshRpowell Aug 4, 2026
90be0bb
fix(skill): document bundle postings and app_bundle_url
joshRpowell Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions skills/hey/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,12 @@ hey box 123 --json # List emails in box (by ID)

Box names: `imbox`, `feedbox`, `trailbox`, `asidebox`, `laterbox`, `bubblebox`

**Response format:** `hey box` returns `{"box": {...}, "postings": [...]}`. Each posting has: `id` (posting ID), `topic_id` (topic ID), `name` (subject), `seen` (read status), `created_at`, `contacts`, `summary`, `app_url`. Use `topic_id` for `hey threads` and `hey reply`.
**Response format:** `hey box --json` returns `{"ok": true, "data": {...box fields..., "postings": [...]}}`. Each posting has an `id` (posting ID), plus fields such as `kind`, `name` (subject), `created_at`, `contacts`, `summary`, `app_url`, and — on bundles — `app_bundle_url`. No posting carries a `topic_id`; see the ID note under Threads for resolving one.

Postings come in two kinds:

- `kind: "topic"` — a single message. `app_url` is `/topics/<id>`.
- `kind: "bundle"` — HEY's per-contact digest, wrapping one or more messages from one sender. `app_url` is `/contacts/<id>`, and `name` is a `•`-joined concatenation of the bundled subjects rather than one email's subject.

### Email - Threads

Expand All @@ -170,7 +175,12 @@ hey threads <topic_id> --json # Read full email thread
hey threads <topic_id> --html # Read with raw HTML content
```

**ID note:** `hey box` returns postings with an `id` (posting ID) and a `topic_id` (topic ID). `hey threads` and `hey reply` expect the **topic ID** — use `topic_id` directly. The `app_url` field also contains the topic ID as a fallback (e.g. `https://app.hey.com/topics/123` → `123`).
**ID note:** `hey threads` and `hey reply` expect a **topic ID**, not a posting ID. Resolve one from the first `/topics/<id>` URL the posting offers:

1. `app_url` — present on every `kind: "topic"` posting.
2. `app_bundle_url` — a `kind: "bundle"` posting has a contact-shaped `app_url`, but a bundle wrapping a single message still points at that one topic here.

If neither is topic-shaped, the posting is a bundle of several messages: it names a contact, not a thread, so no topic ID exists for it. Do not substitute the posting ID — `hey threads <posting-id>` requests `/topics/<posting-id>/entries` and returns not-found. The CLI has no command to list the topics inside a bundle, so ask the user to open it in HEY instead. See issue #156.

### Email - Reply & Compose

Expand Down