npm - @cakemail-org/cakemail-cli - Versions diffs - 1.7.0 → 2.0.0 - Mend

@cakemail-org/cakemail-cli 1.7.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (198) hide show

package/.claude/settings.local.json +12 -0
package/.env.example +40 -0
package/.env.test.example +45 -0
package/CHANGELOG.md +1031 -0
package/README.md +41 -37
package/audit-formats.js +128 -0
package/cakemail.rb +20 -0
package/dist/client.js +1 -1
package/dist/client.js.map +1 -1
package/dist/commands/account.js +1 -1
package/dist/commands/account.js.map +1 -1
package/dist/commands/attributes.js +1 -1
package/dist/commands/attributes.js.map +1 -1
package/dist/commands/campaigns.js +1 -1
package/dist/commands/campaigns.js.map +1 -1
package/dist/commands/contacts.js +1 -1
package/dist/commands/contacts.js.map +1 -1
package/dist/commands/emails.js +1 -1
package/dist/commands/emails.js.map +1 -1
package/dist/commands/interests.js +1 -1
package/dist/commands/interests.js.map +1 -1
package/dist/commands/lists.js +1 -1
package/dist/commands/lists.js.map +1 -1
package/dist/commands/logs.js +1 -1
package/dist/commands/logs.js.map +1 -1
package/dist/commands/reports.js +1 -1
package/dist/commands/reports.js.map +1 -1
package/dist/commands/segments.js +1 -1
package/dist/commands/segments.js.map +1 -1
package/dist/commands/senders.js +1 -1
package/dist/commands/senders.js.map +1 -1
package/dist/commands/suppressed.js +1 -1
package/dist/commands/suppressed.js.map +1 -1
package/dist/commands/tags.js +1 -1
package/dist/commands/tags.js.map +1 -1
package/dist/commands/templates.js +1 -1
package/dist/commands/templates.js.map +1 -1
package/dist/commands/transactional-templates.js +1 -1
package/dist/commands/transactional-templates.js.map +1 -1
package/dist/commands/webhooks.js +1 -1
package/dist/commands/webhooks.js.map +1 -1
package/dist/utils/config.js +2 -2
package/dist/utils/config.js.map +1 -1
package/dist/utils/errors.js +1 -1
package/dist/utils/errors.js.map +1 -1
package/dist/utils/progress.d.ts.map +1 -1
package/dist/utils/progress.js +32 -4
package/dist/utils/progress.js.map +1 -1
package/dist/utils/spinner.d.ts +17 -0
package/dist/utils/spinner.d.ts.map +1 -0
package/dist/utils/spinner.js +43 -0
package/dist/utils/spinner.js.map +1 -0
package/docs/DOCUMENTATION-STANDARD.md +1068 -0
package/docs/README.md +161 -0
package/docs/developer/ARCHITECTURE.md +516 -0
package/docs/developer/AUTH.md +204 -0
package/docs/developer/CONTRIBUTING.md +227 -0
package/docs/developer/DOCUMENTATION_SUMMARY.md +346 -0
package/docs/developer/PROJECT_INDEX.md +365 -0
package/docs/planning/API_COVERAGE.md +1045 -0
package/docs/planning/BACKLOG.md +1159 -0
package/docs/planning/PROFILE_SYSTEM_TASKS.md +287 -0
package/docs/planning/UX_IMPLEMENTATION_PLAN.md +691 -0
package/docs/planning/archive/RELEASE_CHECKLIST_v1.3.0.md +332 -0
package/docs/planning/archive/RELEASE_v1.3.0.md +428 -0
package/docs/planning/archive/cakemail-cli-ux-improvements.md +438 -0
package/docs/planning/cakemail-profile-system-plan.md +1121 -0
package/docs/testing/AI_USER_SIMULATION_DESIGN.md +1342 -0
package/docs/testing/KENOGAMI_BIDIRECTIONAL_FLOW.md +1517 -0
package/docs/testing/KENOGAMI_TRUTH_RECONCILIATION_SYSTEM.md +1369 -0
package/docs/user-manual/.obsidian/app.json +1 -0
package/docs/user-manual/.obsidian/appearance.json +1 -0
package/docs/user-manual/.obsidian/core-plugins.json +33 -0
package/docs/user-manual/.obsidian/workspace.json +167 -0
package/docs/user-manual/01-getting-started/01-installation.md +214 -0
package/docs/user-manual/01-getting-started/02-quick-start.md +432 -0
package/docs/user-manual/01-getting-started/03-authentication.md +448 -0
package/docs/user-manual/01-getting-started/04-configuration.md +430 -0
package/docs/user-manual/01-getting-started/05-output-formats.md +447 -0
package/docs/user-manual/02-core-concepts/01-accounts.md +514 -0
package/docs/user-manual/02-core-concepts/02-profile-system.md +771 -0
package/docs/user-manual/02-core-concepts/03-smart-defaults.md +485 -0
package/docs/user-manual/02-core-concepts/04-authentication-methods.md +435 -0
package/docs/user-manual/02-core-concepts/05-pagination-filtering.md +600 -0
package/docs/user-manual/02-core-concepts/06-error-handling.md +718 -0
package/docs/user-manual/02-core-concepts/07-api-coverage.md +483 -0
package/docs/user-manual/03-email-operations/01-senders.md +490 -0
package/docs/user-manual/03-email-operations/02-templates.md +444 -0
package/docs/user-manual/03-email-operations/03-transactional-emails.md +706 -0
package/docs/user-manual/03-email-operations/04-email-tracking.md +407 -0
package/docs/user-manual/04-campaign-management/01-campaigns-basics.md +394 -0
package/docs/user-manual/04-campaign-management/02-campaign-scheduling.md +630 -0
package/docs/user-manual/04-campaign-management/03-campaign-testing.md +997 -0
package/docs/user-manual/04-campaign-management/04-campaign-lifecycle.md +709 -0
package/docs/user-manual/04-campaign-management/05-campaign-links.md +934 -0
package/docs/user-manual/05-contact-management/01-lists.md +836 -0
package/docs/user-manual/05-contact-management/02-contacts.md +1035 -0
package/docs/user-manual/05-contact-management/03-custom-attributes.md +788 -0
package/docs/user-manual/05-contact-management/04-segments.md +1028 -0
package/docs/user-manual/05-contact-management/05-contact-import-export.md +1031 -0
package/docs/user-manual/06-analytics-reporting/01-campaign-analytics.md +867 -0
package/docs/user-manual/06-analytics-reporting/02-account-reports.md +227 -0
package/docs/user-manual/07-integrations/01-webhooks-integration.md +259 -0
package/docs/user-manual/07-integrations/02-automation.md +326 -0
package/docs/user-manual/08-advanced-usage/01-scripting-patterns.md +672 -0
package/docs/user-manual/08-advanced-usage/02-bulk-operations.md +932 -0
package/docs/user-manual/08-advanced-usage/03-ci-cd-integration.md +892 -0
package/docs/user-manual/08-advanced-usage/04-performance-optimization.md +766 -0
package/docs/user-manual/09-command-reference/01-config.md +776 -0
package/docs/user-manual/09-command-reference/02-account.md +652 -0
package/docs/user-manual/09-command-reference/03-lists.md +958 -0
package/docs/user-manual/09-command-reference/04-contacts.md +1408 -0
package/docs/user-manual/09-command-reference/05-attributes.md +617 -0
package/docs/user-manual/09-command-reference/06-segments.md +894 -0
package/docs/user-manual/09-command-reference/07-senders.md +803 -0
package/docs/user-manual/09-command-reference/08-templates.md +818 -0
package/docs/user-manual/09-command-reference/09-campaigns.md +1250 -0
package/docs/user-manual/09-command-reference/10-emails.md +807 -0
package/docs/user-manual/09-command-reference/11-reports.md +1135 -0
package/docs/user-manual/09-command-reference/12-webhooks.md +773 -0
package/docs/user-manual/09-command-reference/13-suppressed.md +797 -0
package/docs/user-manual/09-command-reference/14-interests.md +630 -0
package/docs/user-manual/09-command-reference/15-tags.md +584 -0
package/docs/user-manual/09-command-reference/16-logs.md +656 -0
package/docs/user-manual/09-command-reference/17-transactional-templates.md +850 -0
package/docs/user-manual/10-troubleshooting/01-common-errors.md +457 -0
package/docs/user-manual/10-troubleshooting/02-authentication-issues.md +558 -0
package/docs/user-manual/10-troubleshooting/03-connection-problems.md +634 -0
package/docs/user-manual/10-troubleshooting/04-debugging.md +725 -0
package/docs/user-manual/11-appendix/04-faq.md +484 -0
package/docs/user-manual/11-appendix/05-glossary.md +250 -0
package/docs/user-manual/README.md +0 -0
package/package.json +13 -61
package/src/cli.ts +125 -0
package/src/client.ts +16 -0
package/src/commands/account.ts +267 -0
package/src/commands/accounts.ts +78 -0
package/src/commands/actions.ts +249 -0
package/src/commands/attributes.ts +139 -0
package/src/commands/campaign-blueprints.ts +106 -0
package/src/commands/campaigns.ts +469 -0
package/src/commands/config.ts +77 -0
package/src/commands/contacts.ts +612 -0
package/src/commands/custom-attributes.ts +127 -0
package/src/commands/dkims.ts +117 -0
package/src/commands/domains.ts +82 -0
package/src/commands/email-apis.ts +569 -0
package/src/commands/emails.ts +197 -0
package/src/commands/forms.ts +283 -0
package/src/commands/interests.ts +155 -0
package/src/commands/links.ts +38 -0
package/src/commands/lists.ts +406 -0
package/src/commands/logos.ts +71 -0
package/src/commands/logs.ts +386 -0
package/src/commands/reports.ts +306 -0
package/src/commands/segments.ts +158 -0
package/src/commands/senders.ts +204 -0
package/src/commands/sub-accounts.ts +271 -0
package/src/commands/suppressed-emails.ts +234 -0
package/src/commands/suppressed.ts +198 -0
package/src/commands/system-emails.ts +85 -0
package/src/commands/tags.ts +146 -0
package/src/commands/tasks.ts +116 -0
package/src/commands/templates.ts +189 -0
package/src/commands/tokens.ts +83 -0
package/src/commands/transactional-emails.ts +374 -0
package/src/commands/transactional-templates.ts +385 -0
package/src/commands/users.ts +506 -0
package/src/commands/webhooks.ts +172 -0
package/src/commands/workflow-blueprints.ts +123 -0
package/src/commands/workflows.ts +265 -0
package/src/types/profile.ts +93 -0
package/src/utils/auth.ts +272 -0
package/src/utils/config-file.ts +96 -0
package/src/utils/config.ts +134 -0
package/src/utils/confirm.ts +32 -0
package/src/utils/defaults.ts +99 -0
package/src/utils/errors.ts +116 -0
package/src/utils/interactive.ts +91 -0
package/src/utils/list-defaults.ts +74 -0
package/src/utils/output.ts +190 -0
package/src/utils/progress.ts +320 -0
package/src/utils/spinner.ts +22 -0
package/tests/IMPLEMENTATION_STATUS.md +258 -0
package/tests/PTY_SETUP.md +118 -0
package/tests/PTY_TESTING_GUIDE.md +507 -0
package/tests/README.md +244 -0
package/tests/fixtures/api-responses/campaigns.json +34 -0
package/tests/fixtures/test-config.json +13 -0
package/tests/helpers/cli-runner.ts +128 -0
package/tests/helpers/mock-server.ts +301 -0
package/tests/helpers/pty-runner.ts +181 -0
package/tests/integration/campaigns-real-api.test.ts +196 -0
package/tests/integration/setup-integration.ts +50 -0
package/tests/pty/campaigns.test.ts +241 -0
package/tests/setup.ts +34 -0
package/tsconfig.json +15 -0
package/vitest.config.ts +28 -0

package/docs/user-manual/03-email-operations/03-transactional-emails.md ADDED Viewed

@@ -0,0 +1,706 @@
+# Transactional Emails
+Learn how to send individual transactional emails using the Cakemail Email API v2.
+## Overview
+Transactional emails are one-to-one messages triggered by user actions or system events. Unlike campaigns (which go to many recipients), transactional emails are sent to individual recipients in real-time.
+**Common use cases:**
+- Welcome emails
+- Password reset notifications
+- Order confirmations
+- Shipping updates
+- Account alerts
+- Invoice receipts
+- Verification codes
+## Prerequisites
+Before sending transactional emails, you need:
+1. **Verified sender email** - See [Senders](/en/cli/command-reference/senders/)
+2. **Valid authentication** - See [Authentication](/en/cli/getting-started/authentication/)
+---
+## Send Command
+The `emails send` command submits a transactional email.
+### Basic Syntax
+```bash
+cakemail emails send \
+  -t <recipient@example.com> \
+  -s "Email Subject" \
+  [content options] \
+  [additional options]
+```
+### Required Options
+- `-t, --to <email>` - Recipient email address
+- `-s, --subject <subject>` - Email subject line
+**Plus one of:**
+- `--html <html>` or `--html-file <path>` - HTML content
+- `--text <text>` or `--text-file <path>` - Plain text content
+- `--template-id <id>` - Use existing template
+---
+## Sending with HTML Content
+### Inline HTML
+Send HTML content directly in the command:
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Welcome to Acme Inc" \
+  --html "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
+```
+**Best for:**
+- Simple emails
+- Quick tests
+- Short content
+### HTML from File
+Load HTML from a file (recommended for complex emails):
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Welcome to Acme Inc" \
+  --html-file templates/welcome.html
+```
+**Best for:**
+- Complex HTML templates
+- Reusable templates
+- Version-controlled content
+**Example HTML file:**
+```html
+<!-- templates/welcome.html -->
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <style>
+    body { font-family: Arial, sans-serif; }
+    .header { background: #007bff; color: white; padding: 20px; }
+    .content { padding: 20px; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>Welcome to Acme Inc!</h1>
+  </div>
+  <div class="content">
+    <p>Hi there,</p>
+    <p>Thanks for signing up. We're excited to have you on board.</p>
+    <p><a href="https://example.com/get-started">Get Started</a></p>
+  </div>
+</body>
+</html>
+```
+---
+## Sending with Plain Text
+### Inline Text
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Welcome to Acme Inc" \
+  --text "Thanks for signing up!"
+```
+### Text from File
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Welcome to Acme Inc" \
+  --text-file templates/welcome.txt
+```
+**Example text file:**
+```text
+Welcome to Acme Inc!
+Thanks for signing up. We're excited to have you on board.
+Get started: https://example.com/get-started
+--
+Acme Inc Team
+```
+---
+## Sending with HTML and Text
+Provide both HTML and plain text (recommended):
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Welcome to Acme Inc" \
+  --html-file templates/welcome.html \
+  --text-file templates/welcome.txt
+```
+**Why both?**
+- **HTML** - Rich formatting for modern email clients
+- **Plain text** - Fallback for text-only clients
+- **Accessibility** - Better for screen readers
+- **Spam filters** - Improves deliverability
+---
+## Using Templates
+Send emails using pre-created templates with variable substitution.
+### Basic Template Usage
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Welcome {{name}}" \
+  --template-id 123 \
+  --params '{"name":"John","company":"Acme Inc"}'
+```
+### Template Parameters
+The `--params` option accepts JSON with variables to substitute:
+```bash
+--params '{"name":"John","email":"john@example.com","orderNumber":"12345"}'
+```
+**Template variables** use double curly braces: `{{variable}}`
+**Example template:**
+```html
+<h1>Hi {{name}},</h1>
+<p>Your order {{orderNumber}} has shipped.</p>
+<p>Track it here: <a href="{{trackingUrl}}">{{trackingUrl}}</a></p>
+```
+**Send command:**
+```bash
+cakemail emails send \
+  -t {{email}} \
+  -s "Order {{orderNumber}} Shipped" \
+  --template-id 456 \
+  --params '{
+    "name":"John",
+    "email":"john@example.com",
+    "orderNumber":"ORD-12345",
+    "trackingUrl":"https://tracking.example.com/ORD-12345"
+  }'
+```
+See [Templates](/en/cli/command-reference/templates/) for template management.
+---
+## Custom Sender
+Override the default sender for specific emails:
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Order Confirmation" \
+  --html "<h1>Your order is confirmed</h1>" \
+  --from-email orders@acme.com \
+  --from-name "Acme Orders"
+```
+**Options:**
+- `--from-email <email>` - Sender email address (must be verified)
+- `--from-name <name>` - Sender display name
+- `--reply-to <email>` - Reply-to address (optional)
+**With reply-to:**
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Support Ticket #12345" \
+  --html "<p>Your ticket has been updated.</p>" \
+  --from-email support@acme.com \
+  --from-name "Acme Support" \
+  --reply-to ticket-12345@support.acme.com
+```
+---
+## Email Tracking
+Enable open and click tracking:
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Newsletter" \
+  --html-file newsletter.html \
+  --tracking
+```
+**What gets tracked:**
+- **Opens** - When recipient opens the email (using tracking pixel)
+- **Clicks** - When recipient clicks links (using redirect URLs)
+**Tracking data available via:**
+```bash
+cakemail emails get <email-id>
+cakemail emails logs --status delivered
+```
+See [Email Tracking](/en/cli/email-operations/email-tracking/) for details.
+---
+## Email Tags
+Tag emails for organization and filtering:
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Welcome Email" \
+  --html-file welcome.html \
+  --tags "welcome,onboarding,automated"
+```
+**Uses for tags:**
+- **Categorization** - Group similar emails
+- **Filtering** - Filter logs by tag
+- **Analytics** - Track performance by category
+- **Automation** - Trigger workflows
+**View all tags:**
+```bash
+cakemail emails tags
+```
+**Filter logs by tag:**
+```bash
+cakemail emails logs --tag welcome
+```
+---
+## Custom Headers
+Add custom email headers:
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Custom Headers Example" \
+  --html "<p>Email with custom headers</p>" \
+  --headers '{"X-Custom-ID":"12345","X-Category":"transactional"}'
+```
+**Common custom headers:**
+- `X-Custom-ID` - Internal tracking ID
+- `X-Category` - Email category
+- `X-Priority` - Email priority
+- `List-Unsubscribe` - Unsubscribe link
+---
+## Attachments
+Attach files to emails:
+```bash
+cakemail emails send \
+  -t recipient@example.com \
+  -s "Invoice #12345" \
+  --html "<p>Please find your invoice attached.</p>" \
+  --attachments '[
+    {
+      "filename":"invoice-12345.pdf",
+      "content":"base64-encoded-content",
+      "type":"application/pdf"
+    }
+  ]'
+```
+**Attachment format:**
+```json
+[
+  {
+    "filename": "document.pdf",
+    "content": "base64-encoded-data",
+    "type": "application/pdf"
+  }
+]
+```
+**Encoding files to base64:**
+```bash
+base64 document.pdf
+```
+**In a script:**
+```bash
+#!/bin/bash
+ATTACHMENT=$(base64 -w 0 invoice.pdf)
+cakemail emails send \
+  -t customer@example.com \
+  -s "Your Invoice" \
+  --html "<p>Invoice attached</p>" \
+  --attachments "[{\"filename\":\"invoice.pdf\",\"content\":\"$ATTACHMENT\",\"type\":\"application/pdf\"}]"
+```
+---
+## Complete Example
+Send a comprehensive transactional email with all features:
+```bash
+cakemail emails send \
+  -t john@example.com \
+  -s "Order #ORD-12345 Confirmed" \
+  --html-file templates/order-confirmation.html \
+  --text-file templates/order-confirmation.txt \
+  --from-email orders@acme.com \
+  --from-name "Acme Orders" \
+  --reply-to support@acme.com \
+  --tracking \
+  --tags "order,confirmation,automated" \
+  --headers '{"X-Order-ID":"ORD-12345","X-Customer-ID":"CUST-789"}' \
+  --attachments '[{"filename":"receipt.pdf","content":"...", "type":"application/pdf"}]'
+```
+---
+## Retrieving Email Details
+Get information about a sent email:
+```bash
+cakemail emails get <email-id>
+```
+**Example output:**
+```json
+{
+  "id": "abc123def456",
+  "to": "recipient@example.com",
+  "subject": "Welcome Email",
+  "status": "delivered",
+  "from": {
+    "email": "hello@acme.com",
+    "name": "Acme Inc"
+  },
+  "tracking": {
+    "opened": true,
+    "opened_at": "2024-06-15T10:30:00Z",
+    "clicks": 2
+  },
+  "tags": ["welcome", "onboarding"],
+  "created_at": "2024-06-15T10:00:00Z",
+  "delivered_at": "2024-06-15T10:01:00Z"
+}
+```
+---
+## Rendering Email HTML
+Preview the rendered HTML of a sent email:
+```bash
+cakemail emails render <email-id>
+```
+**With tracking enabled:**
+```bash
+cakemail emails render <email-id> --tracking
+```
+**As originally submitted:**
+```bash
+cakemail emails render <email-id> --as-submitted
+```
+**Save to file:**
+```bash
+cakemail emails render <email-id> > email.html
+```
+---
+## Viewing Email Logs
+Query email sending activity:
+### All Recent Emails
+```bash
+cakemail emails logs --limit 50
+```
+### Filter by Date Range
+```bash
+cakemail emails logs \
+  --from 2024-06-01 \
+  --to 2024-06-30
+```
+### Filter by Status
+```bash
+# Delivered emails
+cakemail emails logs --status delivered
+# Bounced emails
+cakemail emails logs --status bounced
+# Failed emails
+cakemail emails logs --status failed
+```
+### Filter by Tag
+```bash
+cakemail emails logs --tag welcome
+cakemail emails logs --tag "order-confirmation"
+```
+### Combined Filters
+```bash
+cakemail emails logs \
+  --from 2024-06-01 \
+  --to 2024-06-30 \
+  --tag welcome \
+  --status delivered \
+  --limit 100
+```
+---
+## Practical Examples
+### Example 1: Welcome Email Script
+```bash
+#!/bin/bash
+# send-welcome.sh
+EMAIL=$1
+NAME=$2
+if [ -z "$EMAIL" ] || [ -z "$NAME" ]; then
+  echo "Usage: ./send-welcome.sh <email> <name>"
+  exit 1
+fi
+cakemail emails send \
+  -t "$EMAIL" \
+  -s "Welcome to Acme, $NAME!" \
+  --template-id 123 \
+  --params "{\"name\":\"$NAME\",\"email\":\"$EMAIL\"}" \
+  --tracking \
+  --tags "welcome,automated"
+echo "Welcome email sent to $EMAIL"
+```
+**Usage:**
+```bash
+./send-welcome.sh john@example.com "John Doe"
+```
+### Example 2: Password Reset
+```bash
+#!/bin/bash
+# send-reset.sh
+EMAIL=$1
+RESET_TOKEN=$2
+RESET_URL="https://example.com/reset?token=$RESET_TOKEN"
+cakemail emails send \
+  -t "$EMAIL" \
+  -s "Password Reset Request" \
+  --html "<p>Click to reset: <a href=\"$RESET_URL\">Reset Password</a></p>" \
+  --from-email security@acme.com \
+  --from-name "Acme Security" \
+  --tags "security,password-reset" \
+  --headers "{\"X-Reset-Token\":\"$RESET_TOKEN\"}"
+```
+### Example 3: Order Confirmation with Invoice
+```bash
+#!/bin/bash
+# send-order-confirmation.sh
+EMAIL=$1
+ORDER_ID=$2
+INVOICE_FILE=$3
+# Encode invoice to base64
+INVOICE_BASE64=$(base64 -w 0 "$INVOICE_FILE")
+cakemail emails send \
+  -t "$EMAIL" \
+  -s "Order $ORDER_ID Confirmed" \
+  --template-id 456 \
+  --params "{\"orderNumber\":\"$ORDER_ID\"}" \
+  --tracking \
+  --tags "order,confirmation" \
+  --attachments "[{\"filename\":\"invoice-$ORDER_ID.pdf\",\"content\":\"$INVOICE_BASE64\",\"type\":\"application/pdf\"}]"
+```
+### Example 4: Bulk Transactional Emails
+```bash
+#!/bin/bash
+# bulk-send.sh
+# Read emails from CSV file
+while IFS=',' read -r EMAIL NAME; do
+  echo "Sending to $EMAIL..."
+  cakemail emails send \
+    -t "$EMAIL" \
+    -s "Monthly Newsletter" \
+    --template-id 789 \
+    --params "{\"name\":\"$NAME\"}" \
+    --tracking \
+    --tags "newsletter,monthly"
+  # Rate limiting
+  sleep 0.5
+done < contacts.csv
+echo "All emails sent"
+```
+---
+## Best Practices
+### 1. Always Provide Plain Text
+```bash
+# ✅ Good: HTML + text
+cakemail emails send \
+  -t user@example.com \
+  -s "Subject" \
+  --html-file email.html \
+  --text-file email.txt
+# ❌ Avoid: HTML only
+cakemail emails send \
+  -t user@example.com \
+  -s "Subject" \
+  --html-file email.html
+```
+### 2. Use Templates for Reusable Content
+```bash
+# ✅ Good: Reusable template
+cakemail emails send -t user@example.com -s "Welcome" --template-id 123
+# ❌ Avoid: Hardcoded content for repeated sends
+cakemail emails send -t user@example.com -s "Welcome" --html "..."
+```
+### 3. Tag Your Emails
+```bash
+# ✅ Good: Organized with tags
+cakemail emails send ... --tags "welcome,automated,v2"
+# ❌ Avoid: No categorization
+cakemail emails send ...
+```
+### 4. Use Descriptive Subjects
+```bash
+# ✅ Good: Clear and specific
+-s "Order #12345 Confirmed - Estimated Delivery June 20"
+# ❌ Avoid: Generic
+-s "Order Confirmation"
+```
+### 5. Test Before Bulk Sending
+```bash
+# Test with your own email first
+cakemail emails send -t your@email.com -s "Test" --html-file email.html
+# Then send to recipients
+```
+---
+## Troubleshooting
+### Email Not Delivered
+**Check email status:**
+```bash
+cakemail emails get <email-id>
+```
+**Common issues:**
+1. Unverified sender email
+2. Invalid recipient email
+3. Bounced address
+4. Spam filters
+**View logs:**
+```bash
+cakemail emails logs --status bounced
+```
+### Template Variables Not Substituted
+**Verify params format:**
+```bash
+# ✅ Correct JSON
+--params '{"name":"John","age":30}'
+# ❌ Invalid JSON
+--params '{name:John,age:30}'
+```
+### Tracking Not Working
+**Ensure tracking is enabled:**
+```bash
+cakemail emails send ... --tracking
+```
+**Check email client:**
+- Some clients block tracking pixels
+- Links must be clicked (not just hovered)
+---