GWS Workflow Email Launcher

Convert Gmail messages into Google Tasks entries with a single command -- extract subject lines, snippets, and metadata to create actionable task items from your inbox.

When to Use This Command

Run this command when you want to turn an email into a tracked task without manually copying information between Gmail and Google Tasks.

• You received an email that requires follow-up action and want to track it as a task
• You are processing your inbox and want to convert action items to your task list
• You need to capture email context (subject, snippet) as task notes automatically
• You are building an inbox-to-task automation pipeline

Use it also when:

• You want to route emails to a specific task list instead of the default list
• You need to batch-convert multiple emails into tasks from a script

Quick Start

Copy
# .claude/commands/gws-workflow-email-launcher.md
name: gws-workflow-email-launcher
description: Convert Gmail messages to Google Tasks
arguments:
  message_id: Gmail message ID to convert

Copy
# Convert a Gmail message to a task in the default list
claude gws-workflow-email-launcher "--message-id 18e1a2b3c4d5e6f7"

Expected output:
Task Created:
  Title: "Re: Q1 Budget Review"
  Notes: "Please review the attached budget spreadsheet..."
  Task List: @default
  Source: Gmail message 18e1a2b3c4d5e6f7

Core Concepts

Concept	Description
Message ID	The unique Gmail message identifier for the source email
Task List	The destination task list (defaults to @default)
Title Extraction	The email subject line becomes the task title
Notes Extraction	The email snippet becomes the task notes
Cross-Service	This workflow spans Gmail (read) and Tasks (write) APIs

Email-to-Task Flow:
  Gmail Inbox                    Google Tasks
  ┌──────────┐                  ┌──────────────┐
  │ Message  │ ──> Extract ──>  │ New Task     │
  │ Subject  │     Subject      │ Title: Subj  │
  │ Snippet  │     + Snippet    │ Notes: Snip  │
  └──────────┘                  └──────────────┘

Configuration

Parameter	Default	Description
message-id	required	Gmail message ID to convert
tasklist	@default	Target task list ID
format	json	Output format for the created task
dry-run	false	Preview the task without creating it
params	none	Additional parameters as JSON

Best Practices

1. Use dry-run to preview before creating -- This is a write operation that creates a new task. Use --dry-run or confirm with the user before executing in automated contexts.

2. Specify a task list for organization -- Route emails to specific task lists using --tasklist LIST_ID to keep work tasks separate from personal ones.

3. Get the message ID from Gmail search -- Use gws gmail messages list with a query filter to find the message ID before converting: --params '{"q": "from:[email protected]"}'.

4. Process emails in batch -- Combine with gws gmail messages list output to convert multiple emails: pipe message IDs through a loop calling this command for each one.

5. Check for duplicate tasks -- Before creating a task, list existing tasks to avoid duplicates, especially when running the command as part of an automated pipeline.

Common Issues

1. Invalid message ID -- The message ID must be a valid Gmail message identifier. Use gws gmail messages list to retrieve valid IDs from the user's inbox.

2. Task list not found -- If using a custom task list, verify the list ID with gws tasks tasklists list before specifying it in the --tasklist flag.

3. Missing Gmail read permissions -- This command reads from Gmail and writes to Tasks, requiring both gmail.readonly and tasks OAuth scopes. Re-authenticate with gws auth login if scopes are missing. You can verify current scopes with gws auth status.

Automation Patterns

For inbox-zero workflows, combine this command with Gmail search to process action-item emails in batch. First, list messages matching a label or query: gws gmail messages list --params '{"q": "label:action-needed"}'. Then loop through the message IDs, converting each to a task. After successful conversion, apply a Gmail label like converted-to-task to track which emails have been processed. This prevents duplicate task creation on subsequent runs and keeps your inbox organized.