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/08-templates.md ADDED Viewed

@@ -0,0 +1,818 @@
+# Template Commands
+Manage reusable email templates for campaigns.
+## Overview
+Template commands allow you to:
+- Create reusable HTML and text email templates
+- List and search templates
+- Update template content and metadata
+- Preview/render templates before use
+- Delete unused templates
+- Tag templates for organization
+Templates provide a way to standardize email designs and content across campaigns. They support both HTML and plain text formats.
+**Note**: For transactional email templates, see [Transactional Templates Commands](/en/cli/command-reference/transactional-templates/).
+## Commands
+- [templates list](#templates-list) - List all templates
+- [templates get](#templates-get) - Get template details
+- [templates create](#templates-create) - Create a new template
+- [templates update](#templates-update) - Update template content
+- [templates render](#templates-render) - Preview template
+- [templates delete](#templates-delete) - Delete a template
+---
+## templates list
+List all email templates with filtering and sorting.
+### Usage
+```bash
+cakemail templates list [options]
+```
+### Options
+- `-l, --limit <number>` - Limit number of results per page
+- `-p, --page <number>` - Page number (default: 1)
+- `-f, --filter <filter>` - Filter by name or tags (e.g., `name==Newsletter`)
+- `-s, --sort <sort>` - Sort order (e.g., `+name`, `-created_on`)
+### Examples
+**List all templates:**
+```bash
+$ cakemail templates list
+```
+**Output:**
+```
+┌────────┬─────────────────────┬───────────────┬─────────────────────┐
+│ ID     │ Name                │ Tags          │ Created             │
+├────────┼─────────────────────┼───────────────┼─────────────────────┤
+│ 201    │ Newsletter Template │ newsletter    │ 2024-01-15 10:30:00 │
+│ 202    │ Product Promo       │ promo,product │ 2024-02-01 14:20:00 │
+│ 203    │ Welcome Series      │ onboarding    │ 2024-03-01 09:00:00 │
+└────────┴─────────────────────┴───────────────┴─────────────────────┘
+```
+**Filter by name:**
+```bash
+$ cakemail templates list -f "name==Newsletter"
+```
+**Sort by most recently created:**
+```bash
+$ cakemail templates list -s "-created_on"
+```
+**Sort by name:**
+```bash
+$ cakemail templates list -s "+name"
+```
+**List with pagination:**
+```bash
+$ cakemail templates list -l 10 -p 1
+```
+**Export templates as JSON:**
+```bash
+$ cakemail templates list -f json > templates.json
+```
+**Output:**
+```json
+{
+  "data": [
+    {
+      "id": 201,
+      "name": "Newsletter Template",
+      "tags": ["newsletter"],
+      "created_at": "2024-01-15T10:30:00Z",
+      "updated_at": "2024-02-10T16:45:00Z"
+    }
+  ],
+  "count": 3
+}
+```
+**Find templates by tag:**
+```bash
+$ cakemail templates list -f json | jq '.data[] | select(.tags[] | contains("newsletter"))'
+```
+### Notes
+- Filter syntax: `field==value` with semicolons for multiple filters
+- Sort options: `+name`, `-name`, `+created_on`, `-created_on`, `+updated_on`, `-updated_on`
+- Tags help organize templates by category or purpose
+- Use pagination for accounts with many templates
+### Related Commands
+- [templates get](#templates-get) - View template details
+- [templates create](#templates-create) - Create new template
+- [campaigns create](/en/cli/command-reference/campaigns#campaigns-create) - Use template in campaign
+---
+## templates get
+Get detailed information about a specific template including content.
+### Usage
+```bash
+cakemail templates get <id>
+```
+### Arguments
+- `id` - Template ID (required)
+### Examples
+**Get template details:**
+```bash
+$ cakemail templates get 201
+```
+**Output:**
+```
+{
+  "id": 201,
+  "name": "Newsletter Template",
+  "subject": "Monthly Newsletter - {{month}}",
+  "html": "<!DOCTYPE html>\n<html>\n<head>...</head>\n<body>\n<h1>Welcome!</h1>\n<p>{{content}}</p>\n</body>\n</html>",
+  "text": "Welcome!\n\n{{content}}",
+  "tags": ["newsletter", "monthly"],
+  "created_at": "2024-01-15T10:30:00Z",
+  "updated_at": "2024-02-10T16:45:00Z"
+}
+```
+**Extract HTML content:**
+```bash
+$ cakemail templates get 201 -f json | jq -r '.html' > template.html
+```
+**Extract template name:**
+```bash
+$ cakemail templates get 201 -f json | jq -r '.name'
+```
+**Output:**
+```
+Newsletter Template
+```
+**View template tags:**
+```bash
+$ cakemail templates get 201 -f json | jq '.tags'
+```
+**Output:**
+```json
+["newsletter", "monthly"]
+```
+### Notes
+- Returns complete template including HTML and text content
+- Subject line may include merge tags (e.g., `{{variable}}`)
+- HTML content includes full document structure
+- Text content is plain text alternative
+### Related Commands
+- [templates render](#templates-render) - Preview rendered template
+- [templates update](#templates-update) - Modify template
+- [templates list](#templates-list) - Find template IDs
+---
+## templates create
+Create a new email template with HTML and text content.
+### Usage
+```bash
+cakemail templates create [options]
+```
+### Options
+**Required:**
+- `-n, --name <name>` - Template name
+**Content (at least one required):**
+- `--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
+**Optional:**
+- `--subject <subject>` - Default email subject
+- `--tags <tags>` - Comma-separated tags
+### Examples
+**Create template from file:**
+```bash
+$ cakemail templates create \
+  -n "Newsletter Template" \
+  --html-file ./templates/newsletter.html \
+  --text-file ./templates/newsletter.txt \
+  --subject "Monthly Newsletter"
+```
+**Output:**
+```
+✓ Template created: 201
+{
+  "id": 201,
+  "name": "Newsletter Template",
+  "subject": "Monthly Newsletter"
+}
+```
+**Create template with inline HTML:**
+```bash
+$ cakemail templates create \
+  -n "Simple Promo" \
+  --html "<h1>Special Offer!</h1><p>Save 20% today.</p>" \
+  --text "Special Offer! Save 20% today."
+```
+**Output:**
+```
+✓ Template created: 202
+```
+**Create template with tags:**
+```bash
+$ cakemail templates create \
+  -n "Welcome Email" \
+  --html-file ./welcome.html \
+  --tags "onboarding,welcome,automated"
+```
+**Output:**
+```
+✓ Template created: 203
+{
+  "id": 203,
+  "name": "Welcome Email",
+  "tags": ["onboarding", "welcome", "automated"]
+}
+```
+**Create template with subject and merge tags:**
+```bash
+$ cakemail templates create \
+  -n "Personalized Newsletter" \
+  --html-file ./newsletter.html \
+  --subject "Hi {{first_name}}, here's your newsletter"
+```
+**Create multipart template:**
+```bash
+$ cakemail templates create \
+  -n "Product Update" \
+  --html-file ./update.html \
+  --text-file ./update.txt \
+  --subject "New Product Features" \
+  --tags "product,update"
+```
+### Merge Tags
+Templates support merge tags for personalization:
+- `{{first_name}}` - Contact's first name
+- `{{last_name}}` - Contact's last name
+- `{{email}}` - Contact's email
+- `{{custom_field}}` - Any custom attribute
+### Notes
+- At least one content type (HTML or text) required
+- Both HTML and text recommended for best deliverability
+- Subject line is optional but recommended
+- Tags help organize and filter templates
+- HTML content should include full document structure
+- Merge tags replaced when sending campaign
+### Related Commands
+- [templates get](#templates-get) - View created template
+- [templates render](#templates-render) - Preview template
+- [campaigns create](/en/cli/command-reference/campaigns#campaigns-create) - Use template
+---
+## templates update
+Update an existing template's content or metadata.
+### Usage
+```bash
+cakemail templates update <id> [options]
+```
+### Arguments
+- `id` - Template ID (required)
+### Options
+- `-n, --name <name>` - New template name
+- `--html <html>` - New HTML content (inline)
+- `--html-file <path>` - Path to new HTML file
+- `--text <text>` - New plain text content (inline)
+- `--text-file <path>` - Path to new text file
+- `--subject <subject>` - New default subject
+- `--tags <tags>` - New comma-separated tags (replaces existing)
+### Examples
+**Update template name:**
+```bash
+$ cakemail templates update 201 -n "Monthly Newsletter Template"
+```
+**Output:**
+```
+✓ Template 201 updated
+{
+  "id": 201,
+  "name": "Monthly Newsletter Template"
+}
+```
+**Update HTML content from file:**
+```bash
+$ cakemail templates update 201 --html-file ./templates/newsletter-v2.html
+```
+**Output:**
+```
+✓ Template 201 updated
+```
+**Update subject line:**
+```bash
+$ cakemail templates update 201 --subject "{{month}} Newsletter - Special Edition"
+```
+**Update tags:**
+```bash
+$ cakemail templates update 201 --tags "newsletter,monthly,featured"
+```
+**Update multiple fields:**
+```bash
+$ cakemail templates update 201 \
+  -n "Premium Newsletter" \
+  --html-file ./premium-newsletter.html \
+  --text-file ./premium-newsletter.txt \
+  --subject "Premium: {{month}} Newsletter" \
+  --tags "premium,newsletter"
+```
+**Update only HTML (keep text):**
+```bash
+$ cakemail templates update 201 --html-file ./new-design.html
+```
+**Update inline content:**
+```bash
+$ cakemail templates update 202 \
+  --html "<h1>Updated Offer!</h1><p>Save 30% now.</p>"
+```
+### Notes
+- Only provided fields are updated (partial updates)
+- Tags are replaced entirely (not merged)
+- File paths must point to valid accessible files
+- Changes apply to future campaign uses (not retroactive)
+- Template ID remains the same
+### Related Commands
+- [templates get](#templates-get) - View current template
+- [templates render](#templates-render) - Preview changes
+- [templates create](#templates-create) - Create new template
+---
+## templates render
+Preview/render a template to see how it will appear.
+### Usage
+```bash
+cakemail templates render <id>
+```
+### Arguments
+- `id` - Template ID (required)
+### Examples
+**Render template:**
+```bash
+$ cakemail templates render 201
+```
+**Output:**
+```
+{
+  "html": "<!DOCTYPE html>\n<html>\n<head>...</head>\n<body>\n<h1>Welcome!</h1>\n<p>This is your newsletter.</p>\n</body>\n</html>",
+  "text": "Welcome!\n\nThis is your newsletter.",
+  "subject": "Monthly Newsletter"
+}
+```
+**Save rendered HTML to file:**
+```bash
+$ cakemail templates render 201 -f json | jq -r '.html' > preview.html
+```
+**Open rendered HTML in browser:**
+```bash
+$ cakemail templates render 201 -f json | jq -r '.html' > preview.html && open preview.html
+```
+**View rendered text version:**
+```bash
+$ cakemail templates render 201 -f json | jq -r '.text'
+```
+**Output:**
+```
+Welcome!
+This is your newsletter.
+```
+**Check rendered subject:**
+```bash
+$ cakemail templates render 201 -f json | jq -r '.subject'
+```
+**Output:**
+```
+Monthly Newsletter
+```
+### Notes
+- Shows how template will appear when sent
+- Merge tags shown as-is (not replaced with data)
+- Use to verify template design before sending
+- Useful for testing template changes
+- No emails sent (preview only)
+### Related Commands
+- [templates get](#templates-get) - View template source
+- [templates update](#templates-update) - Modify template
+- [campaigns test](/en/cli/command-reference/campaigns#campaigns-test) - Send test with data
+---
+## templates delete
+Permanently delete a template.
+### Usage
+```bash
+cakemail templates delete <id> [options]
+```
+### Arguments
+- `id` - Template ID (required)
+### Options
+- `-f, --force` - Skip confirmation prompt (use in scripts)
+### Examples
+**Delete template with confirmation:**
+```bash
+$ cakemail templates delete 203
+```
+**Output:**
+```
+⚠ Delete template 203?
+The following will happen:
+  • Template will be permanently deleted
+  • Any campaigns using this template may be affected
+Type 'yes' to confirm: yes
+✓ Template 203 deleted
+```
+**Force delete without confirmation:**
+```bash
+$ cakemail templates delete 203 --force
+```
+**Output:**
+```
+✓ Template 203 deleted
+```
+**Delete in script:**
+```bash
+$ cakemail templates delete 203 --force --batch
+```
+### Notes
+- Deletion is permanent and cannot be undone
+- Historical campaigns using template remain intact
+- Future campaigns cannot use deleted template
+- Template content cannot be recovered
+- Confirmation required unless `--force` is used
+### Related Commands
+- [templates list](#templates-list) - View templates before deletion
+- [templates get](#templates-get) - Review template before deleting
+---
+## Common Workflows
+### Workflow 1: Create Template from Files
+```bash
+# Prepare HTML and text files
+# templates/newsletter.html
+# templates/newsletter.txt
+# Create template
+$ cakemail templates create \
+  -n "March Newsletter" \
+  --html-file ./templates/newsletter.html \
+  --text-file ./templates/newsletter.txt \
+  --subject "{{month}} Newsletter" \
+  --tags "newsletter,monthly"
+# Note template ID (e.g., 201)
+# Preview template
+$ cakemail templates render 201 -f json | jq -r '.html' > preview.html
+$ open preview.html
+# Use in campaign
+$ cakemail campaigns create \
+  -n "March Newsletter Campaign" \
+  -l 123 \
+  -s 101 \
+  --template 201
+```
+### Workflow 2: Update Existing Template
+```bash
+# Get current template
+$ cakemail templates get 201
+# Make changes to local files
+# Edit: templates/newsletter-v2.html
+# Update template
+$ cakemail templates update 201 --html-file ./templates/newsletter-v2.html
+# Preview changes
+$ cakemail templates render 201 -f json | jq -r '.html' > preview-v2.html
+$ open preview-v2.html
+```
+### Workflow 3: Template Organization
+```bash
+# List all templates
+$ cakemail templates list
+# Add tags to organize
+$ cakemail templates update 201 --tags "newsletter,active"
+$ cakemail templates update 202 --tags "promo,seasonal"
+$ cakemail templates update 203 --tags "onboarding,automated"
+# Find templates by tag
+$ cakemail templates list -f json | jq '.data[] | select(.tags[] | contains("newsletter"))'
+```
+### Workflow 4: Template Testing
+```bash
+# Create test template
+$ cakemail templates create \
+  -n "Test Design" \
+  --html-file ./test-design.html \
+  --tags "test"
+# Render preview
+$ cakemail templates render 204 -f json | jq -r '.html' > test.html
+# Review in browser
+$ open test.html
+# If good, update production template
+$ cakemail templates update 201 --html-file ./test-design.html
+# Delete test template
+$ cakemail templates delete 204 --force
+```
+### Workflow 5: Template Backup
+```bash
+# Export all templates
+$ cakemail templates list -f json > templates-backup.json
+# Extract each template's content
+for id in $(jq -r '.data[].id' templates-backup.json); do
+  echo "Backing up template $id..."
+  cakemail templates get $id -f json > "backup-template-$id.json"
+  cakemail templates get $id -f json | jq -r '.html' > "backup-template-$id.html"
+done
+```
+## Best Practices
+1. **Version Control**: Store template HTML/CSS in version control
+2. **Multipart Templates**: Always include both HTML and text versions
+3. **Test Before Use**: Preview templates before using in campaigns
+4. **Consistent Naming**: Use clear, descriptive template names
+5. **Tag Organization**: Use tags to categorize templates
+6. **Responsive Design**: Ensure HTML templates work on mobile devices
+7. **Merge Tags**: Use merge tags for personalization
+8. **Regular Cleanup**: Delete unused or outdated templates
+9. **Backup Important Templates**: Export templates regularly
+## Troubleshooting
+### Error: "Template ID not found"
+Template doesn't exist or was deleted.
+**Solution:**
+```bash
+# List templates to find valid ID
+$ cakemail templates list
+# Use correct template ID
+$ cakemail templates get 201
+```
+### HTML Not Rendering Correctly
+CSS or HTML structure issues.
+**Solution:**
+```bash
+# Preview template
+$ cakemail templates render 201 -f json | jq -r '.html' > test.html
+# Open in browser
+$ open test.html
+# Check for:
+# - Missing closing tags
+# - Invalid CSS
+# - External resource links (should be inline or absolute URLs)
+# Fix and update
+$ cakemail templates update 201 --html-file ./fixed-template.html
+```
+### Merge Tags Not Working
+Incorrect syntax or unsupported field.
+**Solution:**
+```bash
+# Use double curly braces
+# Correct: {{first_name}}
+# Incorrect: {first_name} or $first_name
+# Ensure field exists in contacts
+$ cakemail contacts get 123 501 -f json | jq '.custom_attributes'
+# Update template with correct tags
+$ cakemail templates update 201 --subject "Hi {{first_name}}, welcome!"
+```
+### Template Too Large
+HTML file size exceeds limits.
+**Solution:**
+```bash
+# Check file size
+$ ls -lh ./templates/large-template.html
+# Optimize:
+# - Inline CSS instead of external stylesheets
+# - Compress/minify HTML
+# - Remove unnecessary whitespace
+# - Optimize images (use external URLs)
+# - Remove comments
+# Update with optimized version
+$ cakemail templates update 201 --html-file ./optimized-template.html
+```
+### Cannot Delete Template
+Template may be in use by active campaigns.
+**Solution:**
+```bash
+# Check which campaigns use this template
+$ cakemail campaigns list -f json | jq '.data[] | select(.template_id == 201)'
+# Wait for campaigns to complete
+# Or update campaigns to use different template
+# Then delete
+$ cakemail templates delete 201 --force
+```
+### Text Version Not Displaying
+Text content may be missing or not provided.
+**Solution:**
+```bash
+# Check if template has text content
+$ cakemail templates get 201 -f json | jq '.text'
+# If null or missing, add text version
+$ cakemail templates update 201 --text-file ./newsletter.txt
+# Or generate from HTML (manual process)
+$ cakemail templates get 201 -f json | jq -r '.html' | html2text > newsletter.txt
+$ cakemail templates update 201 --text-file ./newsletter.txt
+```
+---
+**Related Documentation:**
+- [Campaigns Commands](/en/cli/command-reference/campaigns/) - Use templates in campaigns
+- [Transactional Templates Commands](/en/cli/command-reference/transactional-templates/) - Templates for Email API
+- [Senders Commands](/en/cli/command-reference/senders/) - Manage sender identities