# email-report

> Send formatted HTML email reports with conversation summaries and findings. Use when the user asks to email findings, send a summary, or share results via email.

- Author: nikhilpb
- Repository: nikhilpb/skills
- Version: 20260127021128
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/nikhilpb/skills
- Web: https://mule.run/skillshub/@@nikhilpb/skills~email-report:20260127021128

---

---
name: email-report
description: Send formatted HTML email reports with conversation summaries and findings. Use when the user asks to email findings, send a summary, or share results via email.
---

# Email Report

Send formatted HTML email reports via Mailgun API with conversation summaries and findings.

## Quick Start

This skill allows Claude to send professional email reports containing conversation context, findings, and summaries. Perfect for sharing analysis results, research findings, or conversation summaries.

**Quick Example - Send a summary email:**
```python
import sys
sys.path.append('email-report/scripts')
from send_email import send_report

# Send a report with summary and findings
result = send_report(
    to_email="recipient@example.com",
    subject="Research Findings Summary",
    summary="Key findings from our conversation about Swiss weather patterns and optimal hiking conditions.",
    content_items=[
        {
            "title": "Weather Analysis",
            "description": "Compared conditions across 5 Swiss regions",
            "details": "Ticino showed best conditions: 15°C, clear skies, low wind"
        },
        {
            "title": "Route Recommendation",
            "description": "Identified optimal hiking route in Valais",
            "details": "10km moderate trail, 400m elevation gain, 3-4 hours"
        }
    ]
)

if 'error' in result:
    print(f"Error: {result['error']}")
else:
    print(f"✓ Email sent! Message ID: {result['message_id']}")
```

## Environment Setup

Before using this skill, you need to configure Mailgun credentials as environment variables.

### Required Environment Variables

```bash
# Get your API key from: https://app.mailgun.com/app/account/security/api_keys
export MAILGUN_API_KEY="your-mailgun-api-key"

# Your verified Mailgun domain (e.g., mg.yourdomain.com)
export MAILGUN_DOMAIN="your-domain.com"

# Optional: Custom from address (defaults to noreply@DOMAIN)
export MAILGUN_FROM_EMAIL="reports@your-domain.com"
```

### Setting Up Mailgun

1. Sign up at [Mailgun](https://www.mailgun.com/) (free tier: 5,000 emails/month)
2. Verify your domain or use Mailgun's sandbox domain for testing
3. Get your API key from the Mailgun dashboard
4. Set the environment variables as shown above

## Usage Instructions

### 1. Basic Email Report

Send a simple report with summary text:

```python
import sys
sys.path.append('email-report/scripts')
from send_email import send_report

result = send_report(
    to_email="user@example.com",
    subject="Conversation Summary",
    summary="Here's a summary of our conversation about optimal travel routes in Switzerland. We discussed weather conditions, hiking trails, and activity recommendations."
)

if 'error' in result:
    print(f"Failed to send: {result['error']}")
    if 'note' in result:
        print(f"Tip: {result['note']}")
else:
    print(f"Success! Sent to {result['to']}")
    print(f"Message ID: {result['message_id']}")
```

### 2. Detailed Report with Multiple Findings

Send a structured report with multiple content items:

```python
from send_email import send_report

content_items = [
    {
        "title": "Weather Analysis",
        "description": "Compared weather across 5 Swiss regions for next 3 days",
        "details": "Ticino: 15°C, sunny, ideal\nValais: 12°C, partly cloudy, good\nGrisons: 8°C, overcast, moderate"
    },
    {
        "title": "Route Recommendation",
        "description": "Best hiking route based on weather forecast",
        "details": "Route: Via Alta Valle Maggia\nDistance: 10km\nDifficulty: Moderate\nBest day: Tomorrow (Thursday)"
    },
    {
        "title": "Safety Considerations",
        "description": "Weather-related safety notes"
        # Note: 'details' is optional
    }
]

result = send_report(
    to_email="user@example.com",
    subject="Swiss Hiking Activity Planning - Summary Report",
    summary="Based on our analysis of weather conditions and trail options, here are the key findings and recommendations for your hiking trip.",
    content_items=content_items
)
```

### 3. Extract Email from User Prompt

Helper function to extract email addresses from natural language:

```python
from send_email import extract_email_address

# User says: "Send the findings to john.doe@example.com"
email = extract_email_address("Send the findings to john.doe@example.com")
print(email)  # Output: john.doe@example.com

# Works with various formats
extract_email_address("Email it to alice@company.org please")  # alice@company.org
extract_email_address("My email is bob123@test.co.uk")  # bob123@test.co.uk
```

### 4. Validate Email Format

Validate email addresses before sending:

```python
from send_email import validate_email

if validate_email("user@example.com"):
    print("Valid email")
else:
    print("Invalid email format")
```

## Key Functions

### send_report()

Main function to send email reports.

```python
send_report(to_email, subject, summary, content_items=None, from_name="Claude Code")
```

**Parameters:**
- `to_email` (str): Recipient email address
- `subject` (str): Email subject line
- `summary` (str): Summary text for executive summary section
- `content_items` (list, optional): List of findings/items to include
- `from_name` (str, optional): Sender display name

**Content Item Structure:**
```python
{
    "title": "Item Title",           # Required
    "description": "Brief summary",  # Optional
    "details": "Detailed info"       # Optional
}
```

**Returns:**
- Success: `{"success": True, "message_id": "...", "to": "...", "subject": "..."}`
- Error: `{"error": "Error message", "details": "...", "note": "..."}`

### extract_email_address()

Extract email address from text.

```python
email = extract_email_address(text)  # Returns str or None
```

### validate_email()

Validate email format.

```python
is_valid = validate_email(email)  # Returns bool
```

## HTML Report Format

Reports are automatically formatted with:

- **Professional Layout**: Clean, modern design with Claude Code branding
- **Executive Summary**: Highlighted summary section at the top
- **Structured Content**: Each finding/item displayed with title, description, and details
- **Responsive Design**: Mobile-friendly layout that works on all devices
- **Email Client Compatible**: Tested with Gmail, Outlook, Apple Mail
- **Plain Text Fallback**: Includes text version for email clients that don't support HTML

## Error Handling

All functions return dictionaries. Always check for errors:

```python
result = send_report(to_email="user@example.com", subject="Report", summary="Summary")

if 'error' in result:
    print(f"Error: {result['error']}")

    # Additional error details available
    if 'details' in result:
        print(f"Details: {result['details']}")

    if 'note' in result:
        print(f"Tip: {result['note']}")

    return  # Stop processing

# Success case
print(f"Sent to {result['to']}")
```

### Common Errors

**Environment Not Configured:**
```
Error: MAILGUN_API_KEY environment variable not set
Note: Set your Mailgun API key: export MAILGUN_API_KEY='your-key'
```

**Invalid Email:**
```
Error: Invalid email format: not-an-email
Note: Please provide a valid email address
```

**Authentication Failed:**
```
Error: Mailgun API error: 401
Note: Authentication failed - check MAILGUN_API_KEY
```

**Domain Not Verified:**
```
Error: Mailgun API error: 403
Note: Forbidden - verify your domain is authorized
```

## How Claude Uses This Skill

When a user asks to send findings via email, Claude will:

1. **Extract Context**: Summarize the relevant conversation findings
2. **Structure Data**: Organize findings into content items with titles and descriptions
3. **Extract Email**: Parse the recipient email from the user's request
4. **Generate Report**: Call `send_report()` with structured data
5. **Confirm**: Report success or explain any errors

**Example User Prompts:**
- "Summarize and send the findings via email to john@example.com"
- "Email this analysis to alice@company.org"
- "Can you send a summary of our conversation to bob@test.com?"
- "Send the weather comparison results to myemail@domain.com"

## Testing

### Test Email Validation and Extraction

```bash
cd email-report/scripts
python3 send_email.py
```

This runs the built-in test suite showing:
- Email validation tests
- Email extraction from text
- Environment variable checks

### Test HTML Generation

```bash
python3 html_formatter.py
```

Generates a test HTML report saved to `/tmp/test_report.html` that you can open in a browser.

### Test Email Sending

```bash
# Set environment variables
export MAILGUN_API_KEY="your-key"
export MAILGUN_DOMAIN="your-domain.com"
export TEST_EMAIL="your-email@example.com"

# Run test
python3 send_email.py
```

Check your inbox for the test email.

## Troubleshooting

### Environment Variables Not Loading

**Problem:** Error says environment variables not set, but you've set them.

**Solution:**
- Ensure variables are exported: `export MAILGUN_API_KEY="key"`
- Check current shell: `echo $MAILGUN_API_KEY`
- Restart your terminal or re-source your profile

### Email Not Arriving

**Problem:** No error, but email doesn't arrive.

**Solutions:**
1. Check spam/junk folder
2. Verify domain is authorized in Mailgun dashboard
3. Check Mailgun logs: https://app.mailgun.com/app/logs
4. Test with Mailgun sandbox domain first
5. Ensure recipient email is authorized (sandbox domains have restrictions)

### HTML Not Rendering

**Problem:** Email arrives but HTML doesn't display properly.

**Solution:**
- This is normal for some email clients (plain text version will show)
- Test in different clients (Gmail, Outlook, Apple Mail)
- Check Mailgun logs for delivery details

### Rate Limit Errors

**Problem:** Getting rate limit errors from Mailgun.

**Solution:**
- Free tier: 5,000 emails/month
- Upgrade plan or wait for monthly reset
- Check Mailgun dashboard for usage

### Network Errors

**Problem:** URLError or connection timeout.

**Solution:**
- Check internet connection
- Verify firewall allows HTTPS to api.mailgun.net
- Try again in a few moments

## Tips

- **Keep Summaries Concise**: 2-3 sentences work best for executive summary
- **Structure Findings**: Use clear titles and descriptions for content items
- **Test First**: Send to your own email first before sending to others
- **Verify Domain**: Mailgun requires domain verification for production use
- **Use Sandbox**: Mailgun's sandbox domain is perfect for testing
- **Check Logs**: Mailgun dashboard shows detailed logs for debugging
- **Plain Text**: Always included automatically for email client compatibility
- **Character Limits**: Mailgun supports emails up to 25MB

## Data Sources

- **Email Service**: [Mailgun](https://www.mailgun.com/) - Transactional email API
- **HTML Rendering**: Inline CSS for maximum email client compatibility

## Scripts Reference

- `send_email.py` - Main email sending logic with Mailgun API integration
- `html_formatter.py` - HTML report generation with professional styling

## Security Notes

- **Never commit API keys** to version control
- **Use environment variables** for all credentials
- **Validate email addresses** before sending (done automatically)
- **HTML is escaped** to prevent injection attacks
- **HTTPS only** for API communication