sending-emails

name: sending-emails description: | Send emails via Gmail API using FastMCP server with approval workflows. Use when configuring email sending, troubleshooting email delivery, setting up email templates, or managing email rate limits. NOT when reading emails (use watching-gmail skill). NOT when categorizing emails (use watching-gmail skill).

Email Sender MCP Skill

FastMCP server for sending emails via Gmail API.

Quick Start

# Start MCP server
python src/mcp_servers/email_sender.py

# Or via scripts
python scripts/run.py

MCP Tools

1. send_email(to, subject, body, cc, bcc, requires_approval) - Send or queue email
2. send_from_template(template_name, to, variables, requires_approval) - Template-based send
3. archive_email(message_id) - Archive sent email

Production Gotchas ⚠️

Cloud Mode Forces Approval

When FTE_ROLE=cloud, ALL emails are forced to approval workflow regardless of requires_approval flag:

if role == "cloud":
    requires_approval = True  # Always enforced

Recipient Limit (FR-003)

Maximum 5 total recipients (to + cc + bcc combined). Exceeding returns error:

Error: Recipient limit exceeded. Max 5 allowed, got {count}.

Separate Token Files

Sending requires different token than reading:

• token_email.json - For sending (gmail.send scope)
• token.json - For reading (gmail.readonly scope)

Template Subject Required

When using send_from_template, variables MUST include subject:

# ✗ FAILS
send_from_template("welcome.j2", "user@example.com", {"name": "John"})

# ✓ WORKS
send_from_template("welcome.j2", "user@example.com", {"name": "John", "subject": "Welcome!"})

Rate Limit Fail-Safe

When audit log read fails, rate limiting blocks (fail-safe):

except Exception:
    return False  # Block on error, not allow

Rate Limits

Tracked via Vault/Logs/email_audit_log.md.

Approval Workflow

Set requires_approval=True to queue email for human review.

Approval files created in Vault/Pending_Approval/:

• Move to Vault/Approved/ to send
• Delete to reject

Configuration

Required in config/:

• credentials.json - Google OAuth credentials
• token_email.json - Gmail send token (separate from read)

Templates directory: src/templates/email/

Environment Variables

FTE_ROLE=local|cloud  # cloud forces approval for all sends

Verification

Run: python scripts/verify.py

Related Skills

• watching-gmail - Read and categorize incoming emails
• digital-fte-orchestrator - Approval workflow processing