@cakemail-org/cakemail-cli 1.7.0 → 2.0.0

package/docs/user-manual/06-analytics-reporting/02-account-reports.md

@@ -0,0 +1,227 @@
+# Account Reports & Overview
+
+View account-level analytics, usage metrics, and aggregate performance across all campaigns.
+
+## Overview
+
+Account reports provide:
+- Overall account performance metrics
+- Usage and quota tracking
+- Historical trends across all campaigns
+- List health and growth metrics
+- Sender reputation indicators
+
+## Quick Start
+
+### View Account Report
+
+```bash
+$ cakemail reports account
+```
+
+**Output:**
+```
+=== Account Overview ===
+Account ID: 456
+Account Name: My Company
+Plan: Professional
+
+=== Usage ===
+Contacts: 6,789 / 10,000 (67.9%)
+Emails Sent This Month: 45,678 / 100,000 (45.7%)
+
+=== Campaign Performance (Last 30 Days) ===
+Campaigns Sent: 12
+Total Recipients: 142,567
+Average Open Rate: 24.3%
+Average Click Rate: 3.8%
+
+=== List Health ===
+Total Lists: 5
+Total Contacts: 6,789
+Active Subscribers: 6,234 (91.8%)
+Unsubscribed: 412 (6.1%)
+Bounced: 143 (2.1%)
+```
+
+## Account Metrics
+
+### Usage Metrics
+
+```bash
+# Check quota usage
+$ cakemail reports account -f json | jq '{
+  contact_limit: .contact_limit,
+  contacts_used: .contacts_used,
+  contact_usage_pct: (.contacts_used / .contact_limit * 100 | round),
+  email_limit: .email_limit,
+  emails_sent: .emails_sent_this_month,
+  email_usage_pct: (.emails_sent_this_month / .email_limit * 100 | round)
+}'
+```
+
+### Campaign Aggregate Metrics
+
+```bash
+# Get overall performance
+$ cakemail reports account -f json | jq '{
+  total_campaigns: .campaigns_sent_30d,
+  avg_open_rate: .avg_open_rate_30d,
+  avg_click_rate: .avg_click_rate_30d,
+  avg_delivery_rate: .avg_delivery_rate_30d
+}'
+```
+
+## List Health Dashboard
+
+```bash
+#!/bin/bash
+# list-health-dashboard.sh
+
+echo "=== List Health Dashboard ==="
+echo ""
+
+# Get all lists
+LISTS=$(cakemail lists list -f json | jq -r '.data[].id')
+
+TOTAL_CONTACTS=0
+TOTAL_ACTIVE=0
+TOTAL_UNSUB=0
+TOTAL_BOUNCED=0
+
+echo "List ID | Name            | Total | Active | Unsub | Bounce"
+echo "--------|-----------------|-------|--------|-------|--------"
+
+for LIST_ID in $LISTS; do
+  LIST=$(cakemail lists get $LIST_ID -f json)
+
+  NAME=$(echo "$LIST" | jq -r '.name' | cut -c1-15)
+  TOTAL=$(echo "$LIST" | jq -r '.contacts_count')
+  ACTIVE=$(echo "$LIST" | jq -r '.active_contacts')
+  UNSUB=$(echo "$LIST" | jq -r '.unsubscribed')
+  BOUNCE=$(echo "$LIST" | jq -r '.bounced')
+
+  printf "%-7s | %-15s | %5d | %6d | %5d | %6d\n" \
+    "$LIST_ID" "$NAME" $TOTAL $ACTIVE $UNSUB $BOUNCE
+
+  TOTAL_CONTACTS=$((TOTAL_CONTACTS + TOTAL))
+  TOTAL_ACTIVE=$((TOTAL_ACTIVE + ACTIVE))
+  TOTAL_UNSUB=$((TOTAL_UNSUB + UNSUB))
+  TOTAL_BOUNCED=$((TOTAL_BOUNCED + BOUNCE))
+done
+
+echo "--------|-----------------|-------|--------|-------|--------"
+printf "%-7s | %-15s | %5d | %6d | %5d | %6d\n" \
+  "TOTAL" "All Lists" $TOTAL_CONTACTS $TOTAL_ACTIVE $TOTAL_UNSUB $TOTAL_BOUNCED
+
+echo ""
+
+# Calculate health percentage
+HEALTH=$((TOTAL_ACTIVE * 100 / TOTAL_CONTACTS))
+echo "Overall List Health: $HEALTH%"
+
+if [ $HEALTH -ge 90 ]; then
+  echo "  ✅ Excellent"
+elif [ $HEALTH -ge 80 ]; then
+  echo "  ✓ Good"
+elif [ $HEALTH -ge 70 ]; then
+  echo "  ⚠️  Fair - Consider cleanup"
+else
+  echo "  ❌ Poor - Clean lists immediately"
+fi
+```
+
+## Performance Trends
+
+### 30-Day Campaign Summary
+
+```bash
+#!/bin/bash
+# 30day-summary.sh
+
+THIRTY_DAYS_AGO=$(date -d "30 days ago" +%Y-%m-%d)
+
+echo "=== 30-Day Campaign Summary ==="
+echo ""
+
+# Get campaigns from last 30 days
+CAMPAIGNS=$(cakemail campaigns list \
+  --filter "status==sent;delivered_at>=$THIRTY_DAYS_AGO" \
+  -f json | jq -r '.data[].id')
+
+COUNT=0
+TOTAL_RECIPIENTS=0
+TOTAL_OPENS=0
+TOTAL_CLICKS=0
+
+for ID in $CAMPAIGNS; do
+  REPORT=$(cakemail reports campaign $ID -f json 2>/dev/null)
+
+  if [ -n "$REPORT" ]; then
+    RECIPIENTS=$(echo "$REPORT" | jq -r '.total_recipients')
+    OPENS=$(echo "$REPORT" | jq -r '.unique_opens')
+    CLICKS=$(echo "$REPORT" | jq -r '.unique_clicks')
+
+    COUNT=$((COUNT + 1))
+    TOTAL_RECIPIENTS=$((TOTAL_RECIPIENTS + RECIPIENTS))
+    TOTAL_OPENS=$((TOTAL_OPENS + OPENS))
+    TOTAL_CLICKS=$((TOTAL_CLICKS + CLICKS))
+  fi
+done
+
+if [ $COUNT -gt 0 ]; then
+  AVG_OPEN=$((TOTAL_OPENS * 100 / TOTAL_RECIPIENTS))
+  AVG_CLICK=$((TOTAL_CLICKS * 100 / TOTAL_RECIPIENTS))
+
+  echo "Campaigns Sent: $COUNT"
+  echo "Total Recipients: $TOTAL_RECIPIENTS"
+  echo "Total Opens: $TOTAL_OPENS"
+  echo "Total Clicks: $TOTAL_CLICKS"
+  echo ""
+  echo "Average Open Rate: $AVG_OPEN%"
+  echo "Average Click Rate: $AVG_CLICK%"
+else
+  echo "No campaigns sent in last 30 days"
+fi
+```
+
+### Growth Tracking
+
+```bash
+#!/bin/bash
+# track-growth.sh
+
+LOG_FILE="account-growth.log"
+
+# Log current state
+DATE=$(date +%Y-%m-%d)
+ACCOUNT=$(cakemail reports account -f json)
+
+CONTACTS=$(echo "$ACCOUNT" | jq -r '.contacts_used')
+CAMPAIGNS=$(echo "$ACCOUNT" | jq -r '.campaigns_sent_30d')
+
+echo "$DATE,$CONTACTS,$CAMPAIGNS" >> $LOG_FILE
+
+# Show recent growth
+echo "=== Recent Growth ==="
+tail -7 $LOG_FILE | column -t -s','
+```
+
+## Best Practices
+
+1. **Monitor Usage Regularly**
+   - Check quota usage weekly
+   - Plan upgrades before limits
+
+2. **Track List Health**
+   - Review monthly
+   - Clean inactive subscribers
+
+3. **Benchmark Performance**
+   - Compare to industry standards
+   - Track improvements over time
+
+4. **Schedule Reports**
+   - Weekly dashboards
+   - Monthly executive summaries
+

package/docs/user-manual/07-integrations/01-webhooks-integration.md

@@ -0,0 +1,259 @@
+# Webhooks Integration
+
+Receive real-time notifications about email events via webhooks for seamless integration with your applications.
+
+## Overview
+
+Webhooks allow you to:
+- Receive real-time event notifications
+- Integrate with external systems
+- Automate workflows based on email events
+- Track deliverability in your application
+- Sync contact status changes
+
+## Quick Start
+
+### Create Webhook
+
+```bash
+$ cakemail webhooks create \
+  -u "https://api.yourapp.com/webhooks/cakemail" \
+  -e "email.sent,email.opened,email.clicked" \
+  -n "Production Webhook"
+```
+
+**Output:**
+```
+✓ Webhook created successfully
+
+ID: 123
+URL: https://api.yourapp.com/webhooks/cakemail
+Events: email.sent, email.opened, email.clicked
+Status: active
+```
+
+## Available Events
+
+### Email Events
+
+- `email.sent` - Email successfully delivered
+- `email.opened` - Recipient opened email
+- `email.clicked` - Recipient clicked link
+- `email.bounced` - Email bounced
+- `email.unsubscribed` - Recipient unsubscribed
+- `email.spam_complaint` - Marked as spam
+
+### Campaign Events
+
+- `campaign.sent` - Campaign completed sending
+- `campaign.scheduled` - Campaign scheduled
+- `campaign.cancelled` - Campaign cancelled
+
+## Webhook Payload Examples
+
+### Email Sent Event
+
+```json
+{
+  "event": "email.sent",
+  "timestamp": "2024-03-15T10:30:00Z",
+  "data": {
+    "campaign_id": 790,
+    "contact_id": 501,
+    "email": "user@example.com",
+    "message_id": "msg_abc123"
+  }
+}
+```
+
+### Email Opened Event
+
+```json
+{
+  "event": "email.opened",
+  "timestamp": "2024-03-15T11:45:00Z",
+  "data": {
+    "campaign_id": 790,
+    "contact_id": 501,
+    "email": "user@example.com",
+    "user_agent": "Mozilla/5.0...",
+    "ip_address": "192.168.1.1"
+  }
+}
+```
+
+## Integration Examples
+
+### Node.js/Express
+
+```javascript
+const express = require('express');
+const app = express();
+
+app.post('/webhooks/cakemail', express.json(), (req, res) => {
+  const { event, timestamp, data } = req.body;
+
+  switch(event) {
+    case 'email.opened':
+      console.log(`Email opened: ${data.email}`);
+      // Update your database
+      break;
+
+    case 'email.clicked':
+      console.log(`Link clicked: ${data.email}`);
+      // Track engagement
+      break;
+
+    case 'email.bounced':
+      console.log(`Email bounced: ${data.email}`);
+      // Remove from list
+      break;
+  }
+
+  res.status(200).send('OK');
+});
+
+app.listen(3000);
+```
+
+### Python/Flask
+
+```python
+from flask import Flask, request
+import json
+
+app = Flask(__name__)
+
+@app.route('/webhooks/cakemail', methods=['POST'])
+def cakemail_webhook():
+    data = request.json
+    event = data.get('event')
+
+    if event == 'email.opened':
+        email = data['data']['email']
+        # Update database
+        print(f"Email opened: {email}")
+
+    elif event == 'email.clicked':
+        email = data['data']['email']
+        # Track engagement
+        print(f"Link clicked: {email}")
+
+    return '', 200
+
+if __name__ == '__main__':
+    app.run(port=5000)
+```
+
+### PHP
+
+```php
+<?php
+$payload = file_get_contents('php://input');
+$data = json_decode($payload, true);
+
+$event = $data['event'];
+$eventData = $data['data'];
+
+switch($event) {
+    case 'email.opened':
+        $email = $eventData['email'];
+        // Update database
+        error_log("Email opened: $email");
+        break;
+
+    case 'email.clicked':
+        $email = $eventData['email'];
+        // Track engagement
+        error_log("Link clicked: $email");
+        break;
+}
+
+http_response_code(200);
+?>
+```
+
+## Webhook Management
+
+### List Webhooks
+
+```bash
+$ cakemail webhooks list
+```
+
+### Update Webhook
+
+```bash
+$ cakemail webhooks update 123 \
+  -e "email.sent,email.opened,email.clicked,email.bounced"
+```
+
+### Test Webhook
+
+```bash
+$ cakemail webhooks test 123
+```
+
+### Delete Webhook
+
+```bash
+$ cakemail webhooks delete 123 --force
+```
+
+## Security
+
+### Verify Webhook Signature
+
+Cakemail signs webhook payloads with HMAC-SHA256:
+
+```javascript
+const crypto = require('crypto');
+
+function verifyWebhook(payload, signature, secret) {
+  const hmac = crypto
+    .createHmac('sha256', secret)
+    .update(payload)
+    .digest('hex');
+
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(hmac)
+  );
+}
+
+app.post('/webhooks/cakemail', (req, res) => {
+  const signature = req.headers['x-cakemail-signature'];
+  const payload = JSON.stringify(req.body);
+
+  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
+    return res.status(401).send('Invalid signature');
+  }
+
+  // Process webhook
+  res.status(200).send('OK');
+});
+```
+
+## Best Practices
+
+1. **Return 200 Quickly** - Process async
+2. **Verify Signatures** - Security
+3. **Handle Retries** - Idempotent processing
+4. **Log Events** - Debugging
+5. **Monitor Failures** - Alert on errors
+
+## Troubleshooting
+
+### Webhook Not Receiving Events
+
+- Verify URL is publicly accessible
+- Check firewall/security rules
+- Test with `cakemail webhooks test`
+- Check application logs
+
+### Missing Events
+
+- Verify events subscribed
+- Check application response time
+- Monitor webhook status
+