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/09-command-reference/10-emails.md ADDED Viewed

@@ -0,0 +1,807 @@
+# Email Commands
+Send and track transactional emails using the Cakemail Email API v2.
+## Overview
+Email commands allow you to:
+- Send transactional emails with HTML and text content
+- Use templates with dynamic parameters
+- Track email opens and clicks
+- Attach files to emails
+- Tag emails for categorization
+- View email delivery logs and status
+- Render emails for testing
+The Email API v2 is designed for transactional emails (password resets, receipts, notifications) rather than bulk marketing campaigns. For campaigns, use [campaign commands](/en/cli/command-reference/campaigns/).
+## Commands
+- [emails send](#emails-send) - Submit an email to be sent
+- [emails get](#emails-get) - Retrieve email details
+- [emails render](#emails-render) - Render email HTML
+- [emails logs](#emails-logs) - View Email API logs
+- [emails tags](#emails-tags) - List email tags
+---
+## emails send
+Submit a transactional email to be sent via Email API v2.
+### Usage
+```bash
+cakemail emails send [options]
+```
+### Options
+**Required:**
+- `-t, --to <email>` - Recipient email address
+- `-s, --subject <subject>` - Email subject
+**Sender:**
+- `--from-email <email>` - Sender email address
+- `--from-name <name>` - Sender name
+- `--reply-to <email>` - Reply-to email address
+**Content (choose one approach):**
+- `--html <html>` - HTML content (inline)
+- `--html-file <path>` - Path to HTML file
+- `--text <text>` - Plain text content (inline)
+- `--text-file <path>` - Path to text file
+- `--template-id <id>` - Use transactional template
+- `--params <json>` - Template parameters as JSON
+**Additional:**
+- `--tracking` - Enable open and click tracking
+- `--tags <tags>` - Comma-separated tags for categorization
+- `--headers <json>` - Custom headers as JSON object
+- `--attachments <json>` - Attachments as JSON array
+### Examples
+**Send simple HTML email:**
+```bash
+$ cakemail emails send \
+  -t john@example.com \
+  -s "Welcome to Our Service" \
+  --html "<h1>Welcome!</h1><p>Thanks for signing up.</p>" \
+  --from-email noreply@example.com \
+  --from-name "Example Team"
+```
+**Output:**
+```
+✓ Email submitted: email_abc123
+{
+  "id": "email_abc123",
+  "to": "john@example.com",
+  "subject": "Welcome to Our Service",
+  "status": "queued",
+  "submitted_at": "2024-03-15T10:30:00Z"
+}
+```
+**Send email from HTML file:**
+```bash
+$ cakemail emails send \
+  -t jane@example.com \
+  -s "Your Receipt" \
+  --html-file ./templates/receipt.html \
+  --from-email receipts@example.com
+```
+**Output:**
+```
+✓ Email submitted: email_def456
+{
+  "id": "email_def456",
+  "to": "jane@example.com",
+  "subject": "Your Receipt",
+  "status": "queued"
+}
+```
+**Send with tracking enabled:**
+```bash
+$ cakemail emails send \
+  -t user@example.com \
+  -s "Product Update" \
+  --html-file ./updates/march.html \
+  --from-email updates@example.com \
+  --tracking
+```
+**Send with tags for categorization:**
+```bash
+$ cakemail emails send \
+  -t customer@example.com \
+  -s "Order Confirmation" \
+  --html-file ./order-confirmation.html \
+  --from-email orders@example.com \
+  --tags "order,confirmation,automated"
+```
+**Output:**
+```
+✓ Email submitted: email_ghi789
+{
+  "id": "email_ghi789",
+  "to": "customer@example.com",
+  "tags": ["order", "confirmation", "automated"]
+}
+```
+**Send using template with parameters:**
+```bash
+$ cakemail emails send \
+  -t user@example.com \
+  -s "Password Reset" \
+  --template-id 789 \
+  --params '{"reset_link":"https://example.com/reset/abc123","username":"John"}' \
+  --from-email security@example.com
+```
+**Output:**
+```
+✓ Email submitted: email_jkl012
+{
+  "id": "email_jkl012",
+  "template_id": 789,
+  "status": "queued"
+}
+```
+**Send with reply-to and custom headers:**
+```bash
+$ cakemail emails send \
+  -t support-request@example.com \
+  -s "Support Ticket #1234" \
+  --html "<p>A new support ticket has been created.</p>" \
+  --from-email noreply@example.com \
+  --reply-to customer@example.com \
+  --headers '{"X-Ticket-ID":"1234","X-Priority":"high"}'
+```
+**Send multipart (HTML + text):**
+```bash
+$ cakemail emails send \
+  -t user@example.com \
+  -s "Newsletter" \
+  --html-file ./newsletter.html \
+  --text-file ./newsletter.txt \
+  --from-email newsletter@example.com
+```
+### Notes
+- Must provide either content (HTML/text) or template ID
+- HTML and text can be combined for multipart emails
+- Tracking requires HTML content (not available for plain text only)
+- Tags help organize and filter emails in logs
+- Template parameters must be valid JSON
+- Attachments require base64-encoded content in JSON format
+- Rate limits apply based on your account tier
+### Related Commands
+- [emails get](#emails-get) - Check email status
+- [emails logs](#emails-logs) - View delivery logs
+- [transactional-templates list](/en/cli/command-reference/transactional-templates#transactional-templates-list) - List templates
+---
+## emails get
+Retrieve details and status of a submitted email.
+### Usage
+```bash
+cakemail emails get <email-id>
+```
+### Arguments
+- `email-id` - Email ID returned from [emails send](#emails-send)
+### Examples
+**Get email details:**
+```bash
+$ cakemail emails get email_abc123
+```
+**Output:**
+```
+{
+  "id": "email_abc123",
+  "to": "john@example.com",
+  "from": {
+    "email": "noreply@example.com",
+    "name": "Example Team"
+  },
+  "subject": "Welcome to Our Service",
+  "status": "delivered",
+  "submitted_at": "2024-03-15T10:30:00Z",
+  "delivered_at": "2024-03-15T10:30:15Z",
+  "opens": 1,
+  "clicks": 2,
+  "tags": ["welcome", "onboarding"]
+}
+```
+**Check if email was delivered:**
+```bash
+$ cakemail emails get email_abc123 -f json | jq '.status'
+```
+**Output:**
+```
+"delivered"
+```
+**Check email tracking stats:**
+```bash
+$ cakemail emails get email_abc123 -f json | jq '{opens, clicks, status}'
+```
+**Output:**
+```json
+{
+  "opens": 1,
+  "clicks": 2,
+  "status": "delivered"
+}
+```
+### Status Values
+- `queued` - Email accepted and queued for sending
+- `sent` - Email sent to recipient's mail server
+- `delivered` - Email successfully delivered
+- `bounced` - Email bounced (hard or soft bounce)
+- `complained` - Recipient marked as spam
+- `failed` - Email failed to send
+### Notes
+- Status updates in real-time as email is processed
+- Tracking stats only available if tracking was enabled
+- Bounced emails include bounce reason
+- Use this to verify delivery before follow-up actions
+### Related Commands
+- [emails send](#emails-send) - Send email
+- [emails logs](#emails-logs) - View all email logs
+---
+## emails render
+Render the HTML content of a submitted email for testing or preview.
+### Usage
+```bash
+cakemail emails render <email-id> [options]
+```
+### Arguments
+- `email-id` - Email ID to render
+### Options
+- `--as-submitted` - Render original submitted content (before processing)
+- `--tracking` - Enable tracking links in rendered HTML
+### Examples
+**Render email HTML:**
+```bash
+$ cakemail emails render email_abc123
+```
+**Output:**
+```
+{
+  "html": "<!DOCTYPE html>\n<html>\n<head>...</head>\n<body>\n<h1>Welcome!</h1>\n<p>Thanks for signing up.</p>\n</body>\n</html>"
+}
+```
+**Render with tracking enabled:**
+```bash
+$ cakemail emails render email_abc123 --tracking
+```
+**Output:**
+```
+{
+  "html": "<!DOCTYPE html>\n<html>\n<body>\n<h1>Welcome!</h1>\n<p>Thanks for signing up.</p>\n<img src='https://track.cakemail.com/open/...' />\n</body>\n</html>"
+}
+```
+**Save rendered HTML to file:**
+```bash
+$ cakemail emails render email_abc123 -f json | jq -r '.html' > rendered.html
+```
+**Render as originally submitted:**
+```bash
+$ cakemail emails render email_abc123 --as-submitted
+```
+### Notes
+- Useful for debugging email appearance
+- `--tracking` shows how tracking pixels/links are inserted
+- `--as-submitted` bypasses any post-processing
+- Rendered HTML includes full document structure
+- Template variables are replaced with actual values
+### Related Commands
+- [emails get](#emails-get) - Get email metadata
+- [emails send](#emails-send) - Send test email
+---
+## emails logs
+View Email API activity logs with filtering and pagination.
+### Usage
+```bash
+cakemail emails logs [options]
+```
+### Options
+- `--from <date>` - Start date (YYYY-MM-DD format)
+- `--to <date>` - End date (YYYY-MM-DD format)
+- `--tag <tag>` - Filter by tag
+- `--status <status>` - Filter by status (delivered, bounced, etc.)
+- `-l, --limit <number>` - Limit number of results
+- `-p, --page <number>` - Page number
+### Examples
+**View recent logs:**
+```bash
+$ cakemail emails logs
+```
+**Output:**
+```
+┌──────────────┬─────────────────────┬─────────────┬───────────┬─────────────────────┐
+│ ID           │ To                  │ Subject     │ Status    │ Submitted           │
+├──────────────┼─────────────────────┼─────────────┼───────────┼─────────────────────┤
+│ email_abc123 │ john@example.com    │ Welcome...  │ delivered │ 2024-03-15 10:30:00 │
+│ email_def456 │ jane@example.com    │ Receipt     │ delivered │ 2024-03-15 09:15:00 │
+│ email_ghi789 │ bob@example.com     │ Update      │ bounced   │ 2024-03-15 08:00:00 │
+└──────────────┴─────────────────────┴─────────────┴───────────┴─────────────────────┘
+```
+**Filter by date range:**
+```bash
+$ cakemail emails logs --from 2024-03-01 --to 2024-03-15
+```
+**Filter by status:**
+```bash
+$ cakemail emails logs --status bounced
+```
+**Output:**
+```
+┌──────────────┬─────────────────────┬─────────────┬───────────┬─────────────────────┐
+│ ID           │ To                  │ Subject     │ Status    │ Submitted           │
+├──────────────┼─────────────────────┼─────────────┼───────────┼─────────────────────┤
+│ email_ghi789 │ bob@example.com     │ Update      │ bounced   │ 2024-03-15 08:00:00 │
+│ email_jkl012 │ invalid@bad.com     │ Alert       │ bounced   │ 2024-03-14 16:20:00 │
+└──────────────┴─────────────────────┴─────────────┴───────────┴─────────────────────┘
+```
+**Filter by tag:**
+```bash
+$ cakemail emails logs --tag "order" -l 10
+```
+**Output:**
+```
+┌──────────────┬─────────────────────┬─────────────┬───────────┬─────────────┐
+│ ID           │ To                  │ Subject     │ Status    │ Tags        │
+├──────────────┼─────────────────────┼─────────────┼───────────┼─────────────┤
+│ email_mno345 │ customer@ex.com     │ Order #1001 │ delivered │ order,conf  │
+│ email_pqr678 │ buyer@example.com   │ Order #1002 │ delivered │ order,conf  │
+└──────────────┴─────────────────────┴─────────────┴───────────┴─────────────┘
+```
+**Combine filters:**
+```bash
+$ cakemail emails logs \
+  --from 2024-03-01 \
+  --to 2024-03-15 \
+  --status delivered \
+  --tag "welcome" \
+  -l 50
+```
+**Export logs to JSON:**
+```bash
+$ cakemail emails logs --from 2024-03-01 --to 2024-03-15 -f json > email-logs.json
+```
+### Status Filter Values
+- `queued` - Email in queue
+- `sent` - Email sent
+- `delivered` - Successfully delivered
+- `bounced` - Bounced (hard or soft)
+- `complained` - Marked as spam
+- `failed` - Failed to send
+### Notes
+- Logs are retained for 90 days
+- Date range is required for large result sets
+- Use pagination for large log volumes
+- Tags help organize and filter transactional emails
+- Status filter helps identify delivery issues
+### Related Commands
+- [emails get](#emails-get) - Get individual email details
+- [emails tags](#emails-tags) - List all email tags
+- [reports emails](/en/cli/command-reference/reports#reports-emails) - Email API analytics
+---
+## emails tags
+List all tags used in Email API emails.
+### Usage
+```bash
+cakemail emails tags
+```
+### Examples
+**List all email tags:**
+```bash
+$ cakemail emails tags
+```
+**Output:**
+```
+{
+  "tags": [
+    {
+      "name": "order",
+      "count": 1234
+    },
+    {
+      "name": "confirmation",
+      "count": 1180
+    },
+    {
+      "name": "welcome",
+      "count": 456
+    },
+    {
+      "name": "password-reset",
+      "count": 234
+    },
+    {
+      "name": "notification",
+      "count": 890
+    }
+  ]
+}
+```
+**Extract tag names:**
+```bash
+$ cakemail emails tags -f json | jq -r '.tags[].name'
+```
+**Output:**
+```
+order
+confirmation
+welcome
+password-reset
+notification
+```
+**Find most used tags:**
+```bash
+$ cakemail emails tags -f json | jq '.tags | sort_by(.count) | reverse | .[0:5]'
+```
+**Output:**
+```json
+[
+  {"name": "order", "count": 1234},
+  {"name": "confirmation", "count": 1180},
+  {"name": "notification", "count": 890},
+  {"name": "welcome", "count": 456},
+  {"name": "password-reset", "count": 234}
+]
+```
+### Notes
+- Tags are created automatically when used in [emails send](#emails-send)
+- Count shows total emails with each tag
+- Tags are case-sensitive
+- Use tags to organize transactional email types
+- Tags help filter logs and analytics
+### Related Commands
+- [emails send](#emails-send) - Send email with tags
+- [emails logs](#emails-logs) - Filter logs by tag
+---
+## Common Workflows
+### Workflow 1: Send Order Confirmation
+```bash
+# Send confirmation email with tracking
+$ cakemail emails send \
+  -t customer@example.com \
+  -s "Order #1234 Confirmed" \
+  --html-file ./templates/order-confirmation.html \
+  --from-email orders@example.com \
+  --from-name "Example Store" \
+  --tracking \
+  --tags "order,confirmation"
+# Save email ID from output (e.g., email_abc123)
+# Verify delivery
+$ cakemail emails get email_abc123
+# Check if opened
+$ cakemail emails get email_abc123 -f json | jq '{status, opens, clicks}'
+```
+### Workflow 2: Send Password Reset
+```bash
+# Generate reset token (your application logic)
+RESET_TOKEN="abc123xyz"
+RESET_LINK="https://example.com/reset/${RESET_TOKEN}"
+# Send password reset email
+$ cakemail emails send \
+  -t user@example.com \
+  -s "Password Reset Request" \
+  --template-id 789 \
+  --params "{\"reset_link\":\"${RESET_LINK}\",\"username\":\"John\"}" \
+  --from-email security@example.com \
+  --tags "password-reset,automated" \
+  --reply-to support@example.com
+# Monitor delivery
+$ cakemail emails logs --tag "password-reset" -l 1
+```
+### Workflow 3: Test Email Template
+```bash
+# Send test email
+$ cakemail emails send \
+  -t developer@example.com \
+  -s "Test: New Template" \
+  --html-file ./templates/new-design.html \
+  --from-email test@example.com \
+  --tracking
+# Get email ID (e.g., email_test123)
+# Render to verify HTML
+$ cakemail emails render email_test123 -f json | jq -r '.html' > test-render.html
+# Open in browser
+$ open test-render.html
+# Check tracking implementation
+$ cakemail emails render email_test123 --tracking -f json | jq -r '.html' | grep -o 'track.cakemail.com'
+```
+### Workflow 4: Monitor Bounces
+```bash
+# Check recent bounces
+$ cakemail emails logs --status bounced --from 2024-03-01 -l 50
+# Get details of bounced emails
+$ cakemail emails get email_bounce123 -f json | jq '{to, status, bounce_reason}'
+# Export bounced emails for cleanup
+$ cakemail emails logs --status bounced --from 2024-03-01 -f json | \
+  jq -r '.data[] | .to' > bounced-emails.txt
+# Add to suppression list (prevents future sends)
+$ cat bounced-emails.txt | while read email; do
+  cakemail suppressed add -e "$email" -r "hard-bounce"
+done
+```
+### Workflow 5: Daily Email Report
+```bash
+# Create daily report script
+#!/bin/bash
+TODAY=$(date +%Y-%m-%d)
+YESTERDAY=$(date -d "yesterday" +%Y-%m-%d)
+# Export yesterday's email logs
+cakemail emails logs --from $YESTERDAY --to $TODAY -f json > daily-report-$YESTERDAY.json
+# Generate summary
+echo "Email Summary for $YESTERDAY"
+echo "Total emails: $(jq '.count' daily-report-$YESTERDAY.json)"
+echo "Delivered: $(jq '[.data[] | select(.status=="delivered")] | length' daily-report-$YESTERDAY.json)"
+echo "Bounced: $(jq '[.data[] | select(.status=="bounced")] | length' daily-report-$YESTERDAY.json)"
+```
+## Best Practices
+1. **Use Templates**: Create reusable templates for common transactional emails
+2. **Tag Everything**: Tag all emails for better organization and filtering
+3. **Enable Tracking**: Use tracking to measure engagement
+4. **Multipart Emails**: Include both HTML and text for better deliverability
+5. **Reply-To Address**: Set reply-to for customer responses
+6. **Monitor Bounces**: Regularly check bounce logs and clean lists
+7. **Test Before Production**: Use [emails render](#emails-render) to test templates
+8. **Rate Limiting**: Respect API rate limits for bulk sends
+9. **Error Handling**: Always check email status after sending
+10. **Suppression List**: Use suppression list to prevent sending to invalid addresses
+## Troubleshooting
+### Error: "Either HTML, text, or template-id is required"
+Email content is missing.
+**Solution:**
+```bash
+# Provide HTML content
+$ cakemail emails send -t user@example.com -s "Subject" --html "<p>Content</p>" --from-email sender@example.com
+# Or use template
+$ cakemail emails send -t user@example.com -s "Subject" --template-id 123 --from-email sender@example.com
+```
+### Email Status: "bounced"
+Email bounced (invalid address or delivery failure).
+**Solution:**
+```bash
+# Check bounce reason
+$ cakemail emails get email_abc123 -f json | jq '.bounce_reason'
+# Add to suppression list
+$ cakemail suppressed add -e "bounced@example.com" -r "hard-bounce"
+# Verify email address is valid before sending
+```
+### Email Not Tracking
+Tracking not enabled or HTML content missing.
+**Solution:**
+```bash
+# Enable tracking when sending
+$ cakemail emails send -t user@example.com -s "Subject" --html-file content.html --tracking --from-email sender@example.com
+# Verify tracking in rendered HTML
+$ cakemail emails render email_abc123 --tracking | grep "track.cakemail.com"
+```
+### Template Parameters Not Working
+Invalid JSON or missing parameters.
+**Solution:**
+```bash
+# Ensure valid JSON syntax
+$ cakemail emails send \
+  -t user@example.com \
+  -s "Subject" \
+  --template-id 123 \
+  --params '{"name":"John","link":"https://example.com"}' \
+  --from-email sender@example.com
+# Test template first
+$ cakemail transactional-templates render 123 -p '{"name":"John"}'
+```
+### Rate Limit Exceeded
+Sending too many emails too quickly.
+**Solution:**
+```bash
+# Add delays between sends in scripts
+for email in $(cat recipients.txt); do
+  cakemail emails send -t "$email" -s "Subject" --html-file content.html --from-email sender@example.com
+  sleep 1  # 1 second delay
+done
+# Contact support for higher rate limits
+```
+### Email Marked as Spam
+Poor sender reputation or content issues.
+**Solution:**
+```bash
+# Use verified sender address
+$ cakemail senders list
+# Avoid spam trigger words in subject
+# Include unsubscribe link
+# Authenticate domain (SPF, DKIM, DMARC)
+# Check email deliverability score
+```
+### Missing Email Logs
+Logs only retained for 90 days.
+**Solution:**
+```bash
+# Export logs regularly
+$ cakemail emails logs --from 2024-03-01 --to 2024-03-15 -f json > archive-march.json
+# Set up automated exports
+# Create scheduled job to archive logs monthly
+```
+---
+**Related Documentation:**
+- [Transactional Templates Commands](/en/cli/command-reference/transactional-templates/) - Manage email templates
+- [Senders Commands](/en/cli/command-reference/senders/) - Manage sender identities
+- [Suppressed Commands](/en/cli/command-reference/suppressed/) - Manage suppression list
+- [Reports Commands](/en/cli/command-reference/reports/) - Email API analytics
+- [Campaigns Commands](/en/cli/command-reference/campaigns/) - Marketing campaigns