External Actions

External actions modify systems outside Sauna: sending emails, posting messages, creating pages, updating calendars. These use the _action preview pattern to get user approval before execution.

How It Works in Sauna

When you write a file with _action frontmatter, Sauna automatically:

1. Displays a preview card showing the draft content formatted nicely
2. Shows an action button with the text from label (e.g., "Send email")
3. Lets the user edit the draft content before approving
4. Triggers the next task step when the user clicks the button

This creates a seamless approve-and-execute flow: user sees what will happen, can edit it, then clicks to proceed.

The _action Frontmatter

---
_action:
  label: "Send email"
  prompt: "Send this email using the Gmail API with the content below"
  isComplete: false
---

**To:** recipient@example.com
**Subject:** Meeting follow-up

Hi Sarah,

Thanks for your time today...

Fields

Field	Purpose
label	Button text shown to user ("Send email", "Create page", "Post message")
prompt	Instructions for execution—tells agent how to process the draft after approval
isComplete	Always false until user clicks the button and action executes

Content Format

Draft body is markdown for readable preview. The prompt tells the agent how to format for the destination (HTML for Gmail, Block Kit for Slack, Notion blocks, etc.).

What Qualifies as External

Any operation that writes to an external service:

• Email: Gmail send, archive, draft creation
• Messaging: Slack post, Discord message
• Documents: Notion page create/update, Google Docs
• Calendar: Event creation/modification
• Databases: Airtable, spreadsheets
• Tasks: Jira, Linear, Asana tickets

Read-only operations (fetching, searching, listing) don't need the preview pattern.

When to Skip Preview

Skip ONLY if:

1. User's PREFERENCES.md exempts this action type
2. User explicitly says "no confirmation" in their message

Never skip based on your own judgment. External writes require approval unless explicitly exempted.

Examples

Gmail Draft

---
_action:
  label: "Save draft"
  prompt: "Create this Gmail draft using the content below. Format body as HTML."
  isComplete: false
---

**To:** alex@company.com
**Subject:** Q1 Planning

Hi Alex,

Following up on our discussion...

Slack Message

---
_action:
  label: "Send to #engineering"
  prompt: "Send this message to #engineering. Convert to Block Kit if structured."
  isComplete: false
---

**Channel:** #engineering

:rocket: Deployment complete!

The v2.3.1 release is now live...

Notion Page

---
_action:
  label: "Create page"
  prompt: "Create this Notion page. Convert to Notion blocks."
  isComplete: false
---

**Parent:** Meeting Notes database
**Title:** Product Sync - Jan 12

## Attendees
- Sarah, Alex, Jordan

## Decisions
1. Launch date confirmed for Feb 1

Task Pattern

Tasks using this pattern should:

1. Read this slice early in the task
2. Prepare the content through normal steps
3. Write the preview draft with _action frontmatter
4. The next step (usually run: code:) executes after user clicks the button

steps:
  - read: <this slice>
    note: "Preview pattern for external actions"
  # ... content preparation steps ...
  - instruction: |
      Write a preview draft with _action frontmatter.

      Sauna displays this as a preview card with an "[Action]" button.
      User can edit the draft, then click the button to execute.
  - run: code:service.send
    # This step runs after user clicks the button