---
name: oysterun-mail
description: Use when an Oysterun agent or scheduled task needs to create a durable Host-owned Mail item through the injected P34 mail:create capability token and should not know raw Mail API details.
metadata:
  short-description: Send Oysterun Mail
---

# Oysterun Mail

Canonical product skill source lives at `skills/oysterun-mail/`. The repo-local Codex mirror at `.codex/skills/oysterun-mail/` and the Host packaged asset at `host-service/assets/product-skills/oysterun-mail/` are generated mirrors. Run `node tool_scripts/sync_product_skills_to_codex.mjs` after changing this skill and `node tool_scripts/check_product_skill_mirrors.mjs` before review.

Use the bundled helper to create a Host-owned Mail item from scheduler or agent runtime. In repo-local Codex tasks, the mirrored helper path is:

```bash
node .codex/skills/oysterun-mail/scripts/send_mail.mjs \
  --title "Digest ready" \
  --summary "Daily tracker finished" \
  --body-file ./digest.md \
  --body-format auto \
  --source-type scheduler \
  --source-name "Daily tracker" \
  --idempotency-key "$OYSTERUN_SCHEDULE_RUN_ID/digest"
```

When Host injects this skill into a live session, the helper is available at:

```bash
node .claude/skills/oysterun-mail/scripts/send_mail.mjs \
  --title "Digest ready" \
  --body "Daily tracker finished" \
  --idempotency-key "$OYSTERUN_SESSION_ID/digest"
```

The Host injects required runtime env:

```text
OYSTERUN_HOST_ORIGIN
OYSTERUN_MAIL_WRITE_TOKEN
```

`OYSTERUN_CAPABILITY_TOKEN` is accepted as a compatibility fallback when `OYSTERUN_MAIL_WRITE_TOKEN` is not present.

The helper also uses these env values when present:

```text
OYSTERUN_SCHEDULE_ID
OYSTERUN_SCHEDULE_RUN_ID
OYSTERUN_AGENT_ID
```

## Inputs

Required:

- `--title`
- one body source: `--body`, `--body-file`, or stdin

Useful optional fields:

- `--summary`
- `--body-format markdown|html|auto`
- `--source-type`, `--source-name`, `--source-ref`
- `--idempotency-key`
- `--site-url`, `--severity`
- `--tag value` or `--tags one,two`
- `--metadata-json '{"key":"value"}'`
- `--link-json '{"label":"Open","href":"/sites/a/index.html","link_type":"host_site"}'`
- `--link "Open|/sites/a/index.html|host_site"`

For `--body-format auto`, the helper treats the body as HTML only when the trimmed body starts with `<!doctype html`, `<html`, or `<body` case-insensitively. Inline angle-bracket markup remains Markdown.

## Output

On success the helper prints only safe JSON:

```json
{"mail_id":"...","url":"/app/mail/...","created":true}
```

It never prints or persists the capability token. If the Host returns an error body, token-like runtime values are redacted before the error is printed.
