@cakemail-org/cakemail-cli 1.5.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 (234) hide show
  1. package/.claude/settings.local.json +12 -0
  2. package/.env.example +40 -0
  3. package/.env.test.example +45 -0
  4. package/CHANGELOG.md +1031 -0
  5. package/README.md +319 -15
  6. package/audit-formats.js +128 -0
  7. package/cakemail.rb +20 -0
  8. package/dist/cli.js +27 -10
  9. package/dist/cli.js.map +1 -1
  10. package/dist/client.d.ts +2 -0
  11. package/dist/client.d.ts.map +1 -1
  12. package/dist/client.js +16 -6
  13. package/dist/client.js.map +1 -1
  14. package/dist/commands/account.js +1 -1
  15. package/dist/commands/account.js.map +1 -1
  16. package/dist/commands/attributes.js +1 -1
  17. package/dist/commands/attributes.js.map +1 -1
  18. package/dist/commands/campaigns.d.ts.map +1 -1
  19. package/dist/commands/campaigns.js +103 -8
  20. package/dist/commands/campaigns.js.map +1 -1
  21. package/dist/commands/config.d.ts.map +1 -1
  22. package/dist/commands/config.js +63 -4
  23. package/dist/commands/config.js.map +1 -1
  24. package/dist/commands/contacts.d.ts.map +1 -1
  25. package/dist/commands/contacts.js +91 -12
  26. package/dist/commands/contacts.js.map +1 -1
  27. package/dist/commands/emails.js +1 -1
  28. package/dist/commands/emails.js.map +1 -1
  29. package/dist/commands/interests.d.ts +5 -0
  30. package/dist/commands/interests.d.ts.map +1 -0
  31. package/dist/commands/interests.js +172 -0
  32. package/dist/commands/interests.js.map +1 -0
  33. package/dist/commands/lists.d.ts.map +1 -1
  34. package/dist/commands/lists.js +6 -8
  35. package/dist/commands/lists.js.map +1 -1
  36. package/dist/commands/logs.d.ts +5 -0
  37. package/dist/commands/logs.d.ts.map +1 -0
  38. package/dist/commands/logs.js +237 -0
  39. package/dist/commands/logs.js.map +1 -0
  40. package/dist/commands/reports.js +1 -1
  41. package/dist/commands/reports.js.map +1 -1
  42. package/dist/commands/segments.js +1 -1
  43. package/dist/commands/segments.js.map +1 -1
  44. package/dist/commands/senders.d.ts.map +1 -1
  45. package/dist/commands/senders.js +11 -8
  46. package/dist/commands/senders.js.map +1 -1
  47. package/dist/commands/suppressed.js +1 -1
  48. package/dist/commands/suppressed.js.map +1 -1
  49. package/dist/commands/tags.d.ts +5 -0
  50. package/dist/commands/tags.d.ts.map +1 -0
  51. package/dist/commands/tags.js +124 -0
  52. package/dist/commands/tags.js.map +1 -0
  53. package/dist/commands/templates.js +1 -1
  54. package/dist/commands/templates.js.map +1 -1
  55. package/dist/commands/transactional-templates.d.ts +5 -0
  56. package/dist/commands/transactional-templates.d.ts.map +1 -0
  57. package/dist/commands/transactional-templates.js +354 -0
  58. package/dist/commands/transactional-templates.js.map +1 -0
  59. package/dist/commands/webhooks.js +1 -1
  60. package/dist/commands/webhooks.js.map +1 -1
  61. package/dist/utils/auth.d.ts +8 -1
  62. package/dist/utils/auth.d.ts.map +1 -1
  63. package/dist/utils/auth.js +39 -11
  64. package/dist/utils/auth.js.map +1 -1
  65. package/dist/utils/config-file.d.ts +7 -0
  66. package/dist/utils/config-file.d.ts.map +1 -1
  67. package/dist/utils/config-file.js +15 -0
  68. package/dist/utils/config-file.js.map +1 -1
  69. package/dist/utils/config.d.ts +2 -0
  70. package/dist/utils/config.d.ts.map +1 -1
  71. package/dist/utils/config.js +12 -4
  72. package/dist/utils/config.js.map +1 -1
  73. package/dist/utils/errors.js +1 -1
  74. package/dist/utils/errors.js.map +1 -1
  75. package/dist/utils/list-defaults.d.ts +33 -0
  76. package/dist/utils/list-defaults.d.ts.map +1 -0
  77. package/dist/utils/list-defaults.js +52 -0
  78. package/dist/utils/list-defaults.js.map +1 -0
  79. package/dist/utils/output.d.ts.map +1 -1
  80. package/dist/utils/output.js +36 -13
  81. package/dist/utils/output.js.map +1 -1
  82. package/dist/utils/progress.d.ts.map +1 -1
  83. package/dist/utils/progress.js +32 -4
  84. package/dist/utils/progress.js.map +1 -1
  85. package/dist/utils/spinner.d.ts +17 -0
  86. package/dist/utils/spinner.d.ts.map +1 -0
  87. package/dist/utils/spinner.js +43 -0
  88. package/dist/utils/spinner.js.map +1 -0
  89. package/docs/DOCUMENTATION-STANDARD.md +1068 -0
  90. package/docs/README.md +161 -0
  91. package/docs/developer/ARCHITECTURE.md +516 -0
  92. package/docs/developer/AUTH.md +204 -0
  93. package/docs/developer/CONTRIBUTING.md +227 -0
  94. package/docs/developer/DOCUMENTATION_SUMMARY.md +346 -0
  95. package/docs/developer/PROJECT_INDEX.md +365 -0
  96. package/docs/planning/API_COVERAGE.md +1045 -0
  97. package/docs/planning/BACKLOG.md +1159 -0
  98. package/docs/planning/PROFILE_SYSTEM_TASKS.md +287 -0
  99. package/docs/planning/UX_IMPLEMENTATION_PLAN.md +691 -0
  100. package/docs/planning/archive/RELEASE_CHECKLIST_v1.3.0.md +332 -0
  101. package/docs/planning/archive/RELEASE_v1.3.0.md +428 -0
  102. package/docs/planning/archive/cakemail-cli-ux-improvements.md +438 -0
  103. package/docs/planning/cakemail-profile-system-plan.md +1121 -0
  104. package/docs/testing/AI_USER_SIMULATION_DESIGN.md +1342 -0
  105. package/docs/testing/KENOGAMI_BIDIRECTIONAL_FLOW.md +1517 -0
  106. package/docs/testing/KENOGAMI_TRUTH_RECONCILIATION_SYSTEM.md +1369 -0
  107. package/docs/user-manual/.obsidian/app.json +1 -0
  108. package/docs/user-manual/.obsidian/appearance.json +1 -0
  109. package/docs/user-manual/.obsidian/core-plugins.json +33 -0
  110. package/docs/user-manual/.obsidian/workspace.json +167 -0
  111. package/docs/user-manual/01-getting-started/01-installation.md +214 -0
  112. package/docs/user-manual/01-getting-started/02-quick-start.md +432 -0
  113. package/docs/user-manual/01-getting-started/03-authentication.md +448 -0
  114. package/docs/user-manual/01-getting-started/04-configuration.md +430 -0
  115. package/docs/user-manual/01-getting-started/05-output-formats.md +447 -0
  116. package/docs/user-manual/02-core-concepts/01-accounts.md +514 -0
  117. package/docs/user-manual/02-core-concepts/02-profile-system.md +771 -0
  118. package/docs/user-manual/02-core-concepts/03-smart-defaults.md +485 -0
  119. package/docs/user-manual/02-core-concepts/04-authentication-methods.md +435 -0
  120. package/docs/user-manual/02-core-concepts/05-pagination-filtering.md +600 -0
  121. package/docs/user-manual/02-core-concepts/06-error-handling.md +718 -0
  122. package/docs/user-manual/02-core-concepts/07-api-coverage.md +483 -0
  123. package/docs/user-manual/03-email-operations/01-senders.md +490 -0
  124. package/docs/user-manual/03-email-operations/02-templates.md +444 -0
  125. package/docs/user-manual/03-email-operations/03-transactional-emails.md +706 -0
  126. package/docs/user-manual/03-email-operations/04-email-tracking.md +407 -0
  127. package/docs/user-manual/04-campaign-management/01-campaigns-basics.md +394 -0
  128. package/docs/user-manual/04-campaign-management/02-campaign-scheduling.md +630 -0
  129. package/docs/user-manual/04-campaign-management/03-campaign-testing.md +997 -0
  130. package/docs/user-manual/04-campaign-management/04-campaign-lifecycle.md +709 -0
  131. package/docs/user-manual/04-campaign-management/05-campaign-links.md +934 -0
  132. package/docs/user-manual/05-contact-management/01-lists.md +836 -0
  133. package/docs/user-manual/05-contact-management/02-contacts.md +1035 -0
  134. package/docs/user-manual/05-contact-management/03-custom-attributes.md +788 -0
  135. package/docs/user-manual/05-contact-management/04-segments.md +1028 -0
  136. package/docs/user-manual/05-contact-management/05-contact-import-export.md +1031 -0
  137. package/docs/user-manual/06-analytics-reporting/01-campaign-analytics.md +867 -0
  138. package/docs/user-manual/06-analytics-reporting/02-account-reports.md +227 -0
  139. package/docs/user-manual/07-integrations/01-webhooks-integration.md +259 -0
  140. package/docs/user-manual/07-integrations/02-automation.md +326 -0
  141. package/docs/user-manual/08-advanced-usage/01-scripting-patterns.md +672 -0
  142. package/docs/user-manual/08-advanced-usage/02-bulk-operations.md +932 -0
  143. package/docs/user-manual/08-advanced-usage/03-ci-cd-integration.md +892 -0
  144. package/docs/user-manual/08-advanced-usage/04-performance-optimization.md +766 -0
  145. package/docs/user-manual/09-command-reference/01-config.md +776 -0
  146. package/docs/user-manual/09-command-reference/02-account.md +652 -0
  147. package/docs/user-manual/09-command-reference/03-lists.md +958 -0
  148. package/docs/user-manual/09-command-reference/04-contacts.md +1408 -0
  149. package/docs/user-manual/09-command-reference/05-attributes.md +617 -0
  150. package/docs/user-manual/09-command-reference/06-segments.md +894 -0
  151. package/docs/user-manual/09-command-reference/07-senders.md +803 -0
  152. package/docs/user-manual/09-command-reference/08-templates.md +818 -0
  153. package/docs/user-manual/09-command-reference/09-campaigns.md +1250 -0
  154. package/docs/user-manual/09-command-reference/10-emails.md +807 -0
  155. package/docs/user-manual/09-command-reference/11-reports.md +1135 -0
  156. package/docs/user-manual/09-command-reference/12-webhooks.md +773 -0
  157. package/docs/user-manual/09-command-reference/13-suppressed.md +797 -0
  158. package/docs/user-manual/09-command-reference/14-interests.md +630 -0
  159. package/docs/user-manual/09-command-reference/15-tags.md +584 -0
  160. package/docs/user-manual/09-command-reference/16-logs.md +656 -0
  161. package/docs/user-manual/09-command-reference/17-transactional-templates.md +850 -0
  162. package/docs/user-manual/10-troubleshooting/01-common-errors.md +457 -0
  163. package/docs/user-manual/10-troubleshooting/02-authentication-issues.md +558 -0
  164. package/docs/user-manual/10-troubleshooting/03-connection-problems.md +634 -0
  165. package/docs/user-manual/10-troubleshooting/04-debugging.md +725 -0
  166. package/docs/user-manual/11-appendix/04-faq.md +484 -0
  167. package/docs/user-manual/11-appendix/05-glossary.md +250 -0
  168. package/docs/user-manual/README.md +0 -0
  169. package/package.json +13 -47
  170. package/src/cli.ts +125 -0
  171. package/src/client.ts +16 -0
  172. package/src/commands/account.ts +267 -0
  173. package/src/commands/accounts.ts +78 -0
  174. package/src/commands/actions.ts +249 -0
  175. package/src/commands/attributes.ts +139 -0
  176. package/src/commands/campaign-blueprints.ts +106 -0
  177. package/src/commands/campaigns.ts +469 -0
  178. package/src/commands/config.ts +77 -0
  179. package/src/commands/contacts.ts +612 -0
  180. package/src/commands/custom-attributes.ts +127 -0
  181. package/src/commands/dkims.ts +117 -0
  182. package/src/commands/domains.ts +82 -0
  183. package/src/commands/email-apis.ts +569 -0
  184. package/src/commands/emails.ts +197 -0
  185. package/src/commands/forms.ts +283 -0
  186. package/src/commands/interests.ts +155 -0
  187. package/src/commands/links.ts +38 -0
  188. package/src/commands/lists.ts +406 -0
  189. package/src/commands/logos.ts +71 -0
  190. package/src/commands/logs.ts +386 -0
  191. package/src/commands/reports.ts +306 -0
  192. package/src/commands/segments.ts +158 -0
  193. package/src/commands/senders.ts +204 -0
  194. package/src/commands/sub-accounts.ts +271 -0
  195. package/src/commands/suppressed-emails.ts +234 -0
  196. package/src/commands/suppressed.ts +198 -0
  197. package/src/commands/system-emails.ts +85 -0
  198. package/src/commands/tags.ts +146 -0
  199. package/src/commands/tasks.ts +116 -0
  200. package/src/commands/templates.ts +189 -0
  201. package/src/commands/tokens.ts +83 -0
  202. package/src/commands/transactional-emails.ts +374 -0
  203. package/src/commands/transactional-templates.ts +385 -0
  204. package/src/commands/users.ts +506 -0
  205. package/src/commands/webhooks.ts +172 -0
  206. package/src/commands/workflow-blueprints.ts +123 -0
  207. package/src/commands/workflows.ts +265 -0
  208. package/src/types/profile.ts +93 -0
  209. package/src/utils/auth.ts +272 -0
  210. package/src/utils/config-file.ts +96 -0
  211. package/src/utils/config.ts +134 -0
  212. package/src/utils/confirm.ts +32 -0
  213. package/src/utils/defaults.ts +99 -0
  214. package/src/utils/errors.ts +116 -0
  215. package/src/utils/interactive.ts +91 -0
  216. package/src/utils/list-defaults.ts +74 -0
  217. package/src/utils/output.ts +190 -0
  218. package/src/utils/progress.ts +320 -0
  219. package/src/utils/spinner.ts +22 -0
  220. package/tests/IMPLEMENTATION_STATUS.md +258 -0
  221. package/tests/PTY_SETUP.md +118 -0
  222. package/tests/PTY_TESTING_GUIDE.md +507 -0
  223. package/tests/README.md +244 -0
  224. package/tests/fixtures/api-responses/campaigns.json +34 -0
  225. package/tests/fixtures/test-config.json +13 -0
  226. package/tests/helpers/cli-runner.ts +128 -0
  227. package/tests/helpers/mock-server.ts +301 -0
  228. package/tests/helpers/pty-runner.ts +181 -0
  229. package/tests/integration/campaigns-real-api.test.ts +196 -0
  230. package/tests/integration/setup-integration.ts +50 -0
  231. package/tests/pty/campaigns.test.ts +241 -0
  232. package/tests/setup.ts +34 -0
  233. package/tsconfig.json +15 -0
  234. package/vitest.config.ts +28 -0
package/docs/user-manual/03-email-operations/02-templates.md ADDED
@@ -0,0 +1,444 @@
1
+ # Templates
2
+
3
+ Create, manage, and use email templates for consistent, reusable email content.
4
+
5
+ ## Overview
6
+
7
+ Email templates are reusable content structures with variable placeholders. They allow you to:
8
+ - **Maintain consistency** across emails
9
+ - **Save time** with pre-built layouts
10
+ - **Support personalization** with variables
11
+ - **Version control** email designs
12
+ - **A/B test** different versions
13
+
14
+ ## Template Commands
15
+
16
+ ### List Templates
17
+
18
+ ```bash
19
+ cakemail templates list [options]
20
+ ```
21
+
22
+ **Options:**
23
+ - `-l, --limit <number>` - Results per page
24
+ - `-p, --page <number>` - Page number
25
+ - `-f, --filter <filter>` - Filter by name or tags
26
+ - `-s, --sort <sort>` - Sort order
27
+
28
+ **Examples:**
29
+ ```bash
30
+ # All templates
31
+ cakemail templates list
32
+
33
+ # Filter by name
34
+ cakemail templates list --filter "name==Newsletter"
35
+
36
+ # Sort by name
37
+ cakemail templates list --sort "+name"
38
+
39
+ # Recent templates
40
+ cakemail templates list --sort "-created_on" --limit 10
41
+ ```
42
+
43
+ ### Get Template Details
44
+
45
+ ```bash
46
+ cakemail templates get <template-id>
47
+ ```
48
+
49
+ **Example:**
50
+ ```bash
51
+ cakemail templates get 123
52
+ ```
53
+
54
+ ### Create Template
55
+
56
+ ```bash
57
+ cakemail templates create \
58
+ -n "Template Name" \
59
+ [content options] \
60
+ [additional options]
61
+ ```
62
+
63
+ **Required:**
64
+ - `-n, --name <name>` - Template name
65
+
66
+ **Content Options:**
67
+ - `--html <html>` - Inline HTML
68
+ - `--html-file <path>` - HTML from file
69
+ - `--text <text>` - Inline plain text
70
+ - `--text-file <path>` - Text from file
71
+
72
+ **Additional Options:**
73
+ - `--subject <subject>` - Default subject
74
+ - `--tags <tags>` - Comma-separated tags
75
+
76
+ **Examples:**
77
+ ```bash
78
+ # From file
79
+ cakemail templates create \
80
+ -n "Welcome Email" \
81
+ --html-file templates/welcome.html \
82
+ --text-file templates/welcome.txt \
83
+ --subject "Welcome to {{company}}" \
84
+ --tags "welcome,onboarding"
85
+
86
+ # Inline content
87
+ cakemail templates create \
88
+ -n "Simple Template" \
89
+ --html "<h1>Hi {{name}}</h1><p>{{message}}</p>" \
90
+ --subject "Hello {{name}}"
91
+ ```
92
+
93
+ ### Update Template
94
+
95
+ ```bash
96
+ cakemail templates update <template-id> [options]
97
+ ```
98
+
99
+ **Options:**
100
+ - `-n, --name <name>` - New name
101
+ - `--html <html>` or `--html-file <path>` - Update HTML
102
+ - `--text <text>` or `--text-file <path>` - Update text
103
+ - `--subject <subject>` - Update subject
104
+ - `--tags <tags>` - Update tags
105
+
106
+ **Examples:**
107
+ ```bash
108
+ # Update content from file
109
+ cakemail templates update 123 --html-file updated-template.html
110
+
111
+ # Update name and subject
112
+ cakemail templates update 123 \
113
+ -n "Welcome Email v2" \
114
+ --subject "Welcome to Acme, {{name}}!"
115
+
116
+ # Update tags
117
+ cakemail templates update 123 --tags "welcome,v2,active"
118
+ ```
119
+
120
+ ### Render Template
121
+
122
+ Preview the rendered output:
123
+
124
+ ```bash
125
+ cakemail templates render <template-id>
126
+ ```
127
+
128
+ **Example:**
129
+ ```bash
130
+ cakemail templates render 123 > preview.html
131
+ ```
132
+
133
+ ### Delete Template
134
+
135
+ ```bash
136
+ cakemail templates delete <template-id> [--force]
137
+ ```
138
+
139
+ **Examples:**
140
+ ```bash
141
+ # Interactive confirmation
142
+ cakemail templates delete 123
143
+
144
+ # Skip confirmation
145
+ cakemail templates delete 123 --force
146
+ ```
147
+
148
+ ---
149
+
150
+ ## Template Variables
151
+
152
+ Use `{{variable}}` syntax for dynamic content.
153
+
154
+ ### Basic Variables
155
+
156
+ ```html
157
+ <h1>Hi {{name}},</h1>
158
+ <p>Your order {{orderNumber}} has shipped.</p>
159
+ ```
160
+
161
+ ### Common Variables
162
+
163
+ | Variable | Purpose | Example |
164
+ |----------|---------|---------|
165
+ | `{{name}}` | Recipient name | John Doe |
166
+ | `{{firstName}}` | First name | John |
167
+ | `{{email}}` | Email address | john@example.com |
168
+ | `{{company}}` | Company name | Acme Inc |
169
+ | `{{orderNumber}}` | Order ID | ORD-12345 |
170
+ | `{{date}}` | Date | 2024-06-15 |
171
+ | `{{url}}` | Custom URL | https://... |
172
+
173
+ ### Using Variables
174
+
175
+ ```bash
176
+ cakemail emails send \
177
+ -t john@example.com \
178
+ -s "Welcome {{name}}" \
179
+ --template-id 123 \
180
+ --params '{"name":"John","company":"Acme Inc"}'
181
+ ```
182
+
183
+ ---
184
+
185
+ ## Template Structure
186
+
187
+ ### Complete Template Example
188
+
189
+ ```html
190
+ <!DOCTYPE html>
191
+ <html>
192
+ <head>
193
+ <meta charset="utf-8">
194
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
195
+ <title>{{subject}}</title>
196
+ <style>
197
+ body {
198
+ font-family: Arial, sans-serif;
199
+ line-height: 1.6;
200
+ color: #333;
201
+ max-width: 600px;
202
+ margin: 0 auto;
203
+ padding: 20px;
204
+ }
205
+ .header {
206
+ background: #007bff;
207
+ color: white;
208
+ padding: 20px;
209
+ text-align: center;
210
+ }
211
+ .content {
212
+ padding: 20px;
213
+ background: #f9f9f9;
214
+ }
215
+ .button {
216
+ display: inline-block;
217
+ padding: 12px 24px;
218
+ background: #007bff;
219
+ color: white;
220
+ text-decoration: none;
221
+ border-radius: 4px;
222
+ }
223
+ .footer {
224
+ padding: 20px;
225
+ text-align: center;
226
+ font-size: 12px;
227
+ color: #666;
228
+ }
229
+ </style>
230
+ </head>
231
+ <body>
232
+ <div class="header">
233
+ <h1>{{companyName}}</h1>
234
+ </div>
235
+
236
+ <div class="content">
237
+ <h2>Hi {{firstName}},</h2>
238
+ <p>{{message}}</p>
239
+ <p>
240
+ <a href="{{actionUrl}}" class="button">{{actionText}}</a>
241
+ </p>
242
+ </div>
243
+
244
+ <div class="footer">
245
+ <p>&copy; 2024 {{companyName}}. All rights reserved.</p>
246
+ <p>
247
+ <a href="{{unsubscribeUrl}}">Unsubscribe</a> |
248
+ <a href="{{preferencesUrl}}">Preferences</a>
249
+ </p>
250
+ </div>
251
+ </body>
252
+ </html>
253
+ ```
254
+
255
+ ### Plain Text Version
256
+
257
+ ```text
258
+ {{companyName}}
259
+ ======================
260
+
261
+ Hi {{firstName}},
262
+
263
+ {{message}}
264
+
265
+ {{actionText}}: {{actionUrl}}
266
+
267
+ ---
268
+ © 2024 {{companyName}}. All rights reserved.
269
+
270
+ Unsubscribe: {{unsubscribeUrl}}
271
+ Update preferences: {{preferencesUrl}}
272
+ ```
273
+
274
+ ---
275
+
276
+ ## Practical Examples
277
+
278
+ ### Example 1: Welcome Email Template
279
+
280
+ ```bash
281
+ cakemail templates create \
282
+ -n "Welcome Email" \
283
+ --html-file welcome.html \
284
+ --text-file welcome.txt \
285
+ --subject "Welcome to {{companyName}}, {{firstName}}!" \
286
+ --tags "welcome,onboarding"
287
+ ```
288
+
289
+ ### Example 2: Order Confirmation
290
+
291
+ ```bash
292
+ cakemail templates create \
293
+ -n "Order Confirmation" \
294
+ --html-file order-confirmation.html \
295
+ --subject "Order {{orderNumber}} Confirmed" \
296
+ --tags "transactional,order"
297
+ ```
298
+
299
+ ### Example 3: Newsletter Template
300
+
301
+ ```bash
302
+ cakemail templates create \
303
+ -n "Monthly Newsletter" \
304
+ --html-file newsletter.html \
305
+ --subject "{{companyName}} Newsletter - {{month}} {{year}}" \
306
+ --tags "newsletter,marketing"
307
+ ```
308
+
309
+ ---
310
+
311
+ ## Template Management
312
+
313
+ ### Organizing with Tags
314
+
315
+ ```bash
316
+ # Tag by type
317
+ --tags "transactional,order"
318
+ --tags "marketing,newsletter"
319
+ --tags "system,notification"
320
+
321
+ # Tag by version
322
+ --tags "welcome,v2,active"
323
+
324
+ # Tag by audience
325
+ --tags "customers,premium"
326
+ ```
327
+
328
+ ### Filtering by Tags
329
+
330
+ ```bash
331
+ cakemail templates list --filter "tags==newsletter"
332
+ ```
333
+
334
+ ### Template Versioning
335
+
336
+ **Create new version:**
337
+ ```bash
338
+ # Get current template
339
+ cakemail templates get 123 > template-v1.json
340
+
341
+ # Create v2
342
+ cakemail templates create \
343
+ -n "Welcome Email v2" \
344
+ --html-file welcome-v2.html \
345
+ --tags "welcome,v2"
346
+
347
+ # Archive old version
348
+ cakemail templates update 123 --tags "welcome,v1,archived"
349
+ ```
350
+
351
+ ---
352
+
353
+ ## Best Practices
354
+
355
+ ### 1. Always Provide Plain Text
356
+
357
+ ```bash
358
+ cakemail templates create \
359
+ -n "Template" \
360
+ --html-file template.html \
361
+ --text-file template.txt # ← Always include
362
+ ```
363
+
364
+ ### 2. Use Descriptive Names
365
+
366
+ ```bash
367
+ # ✅ Good
368
+ -n "Order Confirmation v2"
369
+
370
+ # ❌ Avoid
371
+ -n "Template 1"
372
+ ```
373
+
374
+ ### 3. Test Before Using
375
+
376
+ ```bash
377
+ # Create template
378
+ TEMPLATE_ID=$(cakemail templates create ... | jq -r '.id')
379
+
380
+ # Test with real data
381
+ cakemail emails send \
382
+ -t test@example.com \
383
+ --template-id $TEMPLATE_ID \
384
+ --params '{"name":"Test User"}'
385
+ ```
386
+
387
+ ### 4. Keep Templates Simple
388
+
389
+ - Avoid complex CSS (email clients vary)
390
+ - Use inline styles where possible
391
+ - Test across email clients
392
+ - Provide fallback content
393
+
394
+ ### 5. Version Your Templates
395
+
396
+ ```bash
397
+ # Store templates in version control
398
+ git add templates/
399
+ git commit -m "Add welcome email v2"
400
+
401
+ # Tag template in Cakemail
402
+ --tags "welcome,v2,production"
403
+ ```
404
+
405
+ ---
406
+
407
+ ## Troubleshooting
408
+
409
+ ### Variables Not Substituting
410
+
411
+ **Check JSON format:**
412
+ ```bash
413
+ # ✅ Correct
414
+ --params '{"name":"John"}'
415
+
416
+ # ❌ Invalid
417
+ --params '{name:John}'
418
+ ```
419
+
420
+ ### Template Rendering Issues
421
+
422
+ ```bash
423
+ # Preview template
424
+ cakemail templates render 123 > preview.html
425
+
426
+ # Open in browser to check
427
+ open preview.html
428
+ ```
429
+
430
+ ### HTML Not Displaying
431
+
432
+ **Common issues:**
433
+ - Missing DOCTYPE
434
+ - Unsupported CSS
435
+ - Invalid HTML structure
436
+
437
+ **Test with simple HTML first:**
438
+ ```html
439
+ <h1>Hi {{name}}</h1>
440
+ <p>This is a test.</p>
441
+ ```
442
+
443
+ ---
444
+