inbox

---
name: inbox
description: Check all Gmail inbox emails (read and unread) using the GWS CLI. Use this skill whenever the user wants to see their full inbox, all recent emails, asks "what's in my inbox", "show my emails", "list my emails", "recent emails", "inbox", "show me my mail", "what emails do I have", or any variation of wanting to see all inbox messages regardless of read status. Also triggers on "/inbox". Unlike /unread which only shows unread, this shows everything in the inbox.
---

# Inbox — Full Gmail Inbox View (GWS CLI)

You show the user's full Gmail inbox — read and unread. This is the "open Gmail and look at the list" experience.

## Workflow

### Step 1: Fetch inbox messages

```bash
gws gmail users messages list --params '{"userId": "me", "q": "in:inbox", "maxResults": 15}'
```

If the user asked for something specific, adjust:
- From someone: `"in:inbox from:adi"`
- Date range: `"in:inbox after:2026/03/15"`
- With attachment: `"in:inbox has:attachment"`
- Search term: `"in:inbox meeting agenda"`
- More results: increase `maxResults` (up to 50 for "show me everything")

### Step 2: Fetch metadata for each message

For each message ID, fetch (can run multiple in parallel):

```bash
gws gmail users messages get --params '{"userId": "me", "id": "<message-id>", "format": "metadata"}'
```

Extract:
- **From**: sender name + email
- **Subject**: subject line
- **Date**: from the Date header
- **snippet**: preview text (already in response)
- **labelIds**: check for UNREAD, IMPORTANT, STARRED, CATEGORY_* labels

### Step 3: Present the inbox

Show a clean table with read/unread status:

```
📬 Inbox (15 most recent)

| # | Status | Date | From | Subject |
|---|--------|------|------|---------|
| 1 | ● | Mar 19 | Adi (AgentMail) | Headless SaaS is coming... |
| 2 | ● | Mar 10 | Adi (AgentMail) | We raised $6M to give every... |
| 3 | ○ | Mar 8 | GitHub | [openclaw] New issue #42 |
| 4 | ○ | Mar 5 | Google Cloud | Your billing statement |
```

- **●** = unread, **○** = read
- Bold the row or subject for unread messages
- Format dates as "Mon DD" (or "HH:MM" if today)
- Shorten From to name only, domain/org in parens for automated senders
- Truncate subjects at ~50 chars with "..."
- If a message is IMPORTANT or STARRED, add a marker

### Step 4: Offer next actions

One line: "Want to read, reply to, or search for anything specific?"

## Reading a full email

If the user asks to read one ("read #3", "open the GitHub one"), fetch the full message:

```bash
gws gmail users messages get --params '{"userId": "me", "id": "<message-id>", "format": "full"}'
```

Parse the body from `payload.parts` (look for `text/plain` or `text/html`) or `payload.body.data` for simple messages. Decode the base64 data. Present cleanly with full headers (From, To, Subject, Date) at the top.

## Pagination

If the user wants more ("show more", "older emails", "next page"), the initial list response includes a `nextPageToken`. Use it:

```bash
gws gmail users messages list --params '{"userId": "me", "q": "in:inbox", "maxResults": 15, "pageToken": "<token>"}'
```

## If GWS auth fails

Tell the user: "Gmail auth is expired. Run `! gws auth login` to re-authenticate."