@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/09-command-reference/08-templates.md ADDED
@@ -0,0 +1,818 @@
1
+ # Template Commands
2
+
3
+ Manage reusable email templates for campaigns.
4
+
5
+ ## Overview
6
+
7
+ Template commands allow you to:
8
+ - Create reusable HTML and text email templates
9
+ - List and search templates
10
+ - Update template content and metadata
11
+ - Preview/render templates before use
12
+ - Delete unused templates
13
+ - Tag templates for organization
14
+
15
+ Templates provide a way to standardize email designs and content across campaigns. They support both HTML and plain text formats.
16
+
17
+ **Note**: For transactional email templates, see [Transactional Templates Commands](/en/cli/command-reference/transactional-templates/).
18
+
19
+ ## Commands
20
+
21
+ - [templates list](#templates-list) - List all templates
22
+ - [templates get](#templates-get) - Get template details
23
+ - [templates create](#templates-create) - Create a new template
24
+ - [templates update](#templates-update) - Update template content
25
+ - [templates render](#templates-render) - Preview template
26
+ - [templates delete](#templates-delete) - Delete a template
27
+
28
+ ---
29
+
30
+ ## templates list
31
+
32
+ List all email templates with filtering and sorting.
33
+
34
+ ### Usage
35
+
36
+ ```bash
37
+ cakemail templates list [options]
38
+ ```
39
+
40
+ ### Options
41
+
42
+ - `-l, --limit <number>` - Limit number of results per page
43
+ - `-p, --page <number>` - Page number (default: 1)
44
+ - `-f, --filter <filter>` - Filter by name or tags (e.g., `name==Newsletter`)
45
+ - `-s, --sort <sort>` - Sort order (e.g., `+name`, `-created_on`)
46
+
47
+ ### Examples
48
+
49
+ **List all templates:**
50
+
51
+ ```bash
52
+ $ cakemail templates list
53
+ ```
54
+
55
+ **Output:**
56
+ ```
57
+ ┌────────┬─────────────────────┬───────────────┬─────────────────────┐
58
+ │ ID │ Name │ Tags │ Created │
59
+ ├────────┼─────────────────────┼───────────────┼─────────────────────┤
60
+ │ 201 │ Newsletter Template │ newsletter │ 2024-01-15 10:30:00 │
61
+ │ 202 │ Product Promo │ promo,product │ 2024-02-01 14:20:00 │
62
+ │ 203 │ Welcome Series │ onboarding │ 2024-03-01 09:00:00 │
63
+ └────────┴─────────────────────┴───────────────┴─────────────────────┘
64
+ ```
65
+
66
+ **Filter by name:**
67
+
68
+ ```bash
69
+ $ cakemail templates list -f "name==Newsletter"
70
+ ```
71
+
72
+ **Sort by most recently created:**
73
+
74
+ ```bash
75
+ $ cakemail templates list -s "-created_on"
76
+ ```
77
+
78
+ **Sort by name:**
79
+
80
+ ```bash
81
+ $ cakemail templates list -s "+name"
82
+ ```
83
+
84
+ **List with pagination:**
85
+
86
+ ```bash
87
+ $ cakemail templates list -l 10 -p 1
88
+ ```
89
+
90
+ **Export templates as JSON:**
91
+
92
+ ```bash
93
+ $ cakemail templates list -f json > templates.json
94
+ ```
95
+
96
+ **Output:**
97
+ ```json
98
+ {
99
+ "data": [
100
+ {
101
+ "id": 201,
102
+ "name": "Newsletter Template",
103
+ "tags": ["newsletter"],
104
+ "created_at": "2024-01-15T10:30:00Z",
105
+ "updated_at": "2024-02-10T16:45:00Z"
106
+ }
107
+ ],
108
+ "count": 3
109
+ }
110
+ ```
111
+
112
+ **Find templates by tag:**
113
+
114
+ ```bash
115
+ $ cakemail templates list -f json | jq '.data[] | select(.tags[] | contains("newsletter"))'
116
+ ```
117
+
118
+ ### Notes
119
+
120
+ - Filter syntax: `field==value` with semicolons for multiple filters
121
+ - Sort options: `+name`, `-name`, `+created_on`, `-created_on`, `+updated_on`, `-updated_on`
122
+ - Tags help organize templates by category or purpose
123
+ - Use pagination for accounts with many templates
124
+
125
+ ### Related Commands
126
+
127
+ - [templates get](#templates-get) - View template details
128
+ - [templates create](#templates-create) - Create new template
129
+ - [campaigns create](/en/cli/command-reference/campaigns#campaigns-create) - Use template in campaign
130
+
131
+ ---
132
+
133
+ ## templates get
134
+
135
+ Get detailed information about a specific template including content.
136
+
137
+ ### Usage
138
+
139
+ ```bash
140
+ cakemail templates get <id>
141
+ ```
142
+
143
+ ### Arguments
144
+
145
+ - `id` - Template ID (required)
146
+
147
+ ### Examples
148
+
149
+ **Get template details:**
150
+
151
+ ```bash
152
+ $ cakemail templates get 201
153
+ ```
154
+
155
+ **Output:**
156
+ ```
157
+ {
158
+ "id": 201,
159
+ "name": "Newsletter Template",
160
+ "subject": "Monthly Newsletter - {{month}}",
161
+ "html": "<!DOCTYPE html>\n<html>\n<head>...</head>\n<body>\n<h1>Welcome!</h1>\n<p>{{content}}</p>\n</body>\n</html>",
162
+ "text": "Welcome!\n\n{{content}}",
163
+ "tags": ["newsletter", "monthly"],
164
+ "created_at": "2024-01-15T10:30:00Z",
165
+ "updated_at": "2024-02-10T16:45:00Z"
166
+ }
167
+ ```
168
+
169
+ **Extract HTML content:**
170
+
171
+ ```bash
172
+ $ cakemail templates get 201 -f json | jq -r '.html' > template.html
173
+ ```
174
+
175
+ **Extract template name:**
176
+
177
+ ```bash
178
+ $ cakemail templates get 201 -f json | jq -r '.name'
179
+ ```
180
+
181
+ **Output:**
182
+ ```
183
+ Newsletter Template
184
+ ```
185
+
186
+ **View template tags:**
187
+
188
+ ```bash
189
+ $ cakemail templates get 201 -f json | jq '.tags'
190
+ ```
191
+
192
+ **Output:**
193
+ ```json
194
+ ["newsletter", "monthly"]
195
+ ```
196
+
197
+ ### Notes
198
+
199
+ - Returns complete template including HTML and text content
200
+ - Subject line may include merge tags (e.g., `{{variable}}`)
201
+ - HTML content includes full document structure
202
+ - Text content is plain text alternative
203
+
204
+ ### Related Commands
205
+
206
+ - [templates render](#templates-render) - Preview rendered template
207
+ - [templates update](#templates-update) - Modify template
208
+ - [templates list](#templates-list) - Find template IDs
209
+
210
+ ---
211
+
212
+ ## templates create
213
+
214
+ Create a new email template with HTML and text content.
215
+
216
+ ### Usage
217
+
218
+ ```bash
219
+ cakemail templates create [options]
220
+ ```
221
+
222
+ ### Options
223
+
224
+ **Required:**
225
+ - `-n, --name <name>` - Template name
226
+
227
+ **Content (at least one required):**
228
+ - `--html <html>` - HTML content (inline)
229
+ - `--html-file <path>` - Path to HTML file
230
+ - `--text <text>` - Plain text content (inline)
231
+ - `--text-file <path>` - Path to text file
232
+
233
+ **Optional:**
234
+ - `--subject <subject>` - Default email subject
235
+ - `--tags <tags>` - Comma-separated tags
236
+
237
+ ### Examples
238
+
239
+ **Create template from file:**
240
+
241
+ ```bash
242
+ $ cakemail templates create \
243
+ -n "Newsletter Template" \
244
+ --html-file ./templates/newsletter.html \
245
+ --text-file ./templates/newsletter.txt \
246
+ --subject "Monthly Newsletter"
247
+ ```
248
+
249
+ **Output:**
250
+ ```
251
+ ✓ Template created: 201
252
+ {
253
+ "id": 201,
254
+ "name": "Newsletter Template",
255
+ "subject": "Monthly Newsletter"
256
+ }
257
+ ```
258
+
259
+ **Create template with inline HTML:**
260
+
261
+ ```bash
262
+ $ cakemail templates create \
263
+ -n "Simple Promo" \
264
+ --html "<h1>Special Offer!</h1><p>Save 20% today.</p>" \
265
+ --text "Special Offer! Save 20% today."
266
+ ```
267
+
268
+ **Output:**
269
+ ```
270
+ ✓ Template created: 202
271
+ ```
272
+
273
+ **Create template with tags:**
274
+
275
+ ```bash
276
+ $ cakemail templates create \
277
+ -n "Welcome Email" \
278
+ --html-file ./welcome.html \
279
+ --tags "onboarding,welcome,automated"
280
+ ```
281
+
282
+ **Output:**
283
+ ```
284
+ ✓ Template created: 203
285
+ {
286
+ "id": 203,
287
+ "name": "Welcome Email",
288
+ "tags": ["onboarding", "welcome", "automated"]
289
+ }
290
+ ```
291
+
292
+ **Create template with subject and merge tags:**
293
+
294
+ ```bash
295
+ $ cakemail templates create \
296
+ -n "Personalized Newsletter" \
297
+ --html-file ./newsletter.html \
298
+ --subject "Hi {{first_name}}, here's your newsletter"
299
+ ```
300
+
301
+ **Create multipart template:**
302
+
303
+ ```bash
304
+ $ cakemail templates create \
305
+ -n "Product Update" \
306
+ --html-file ./update.html \
307
+ --text-file ./update.txt \
308
+ --subject "New Product Features" \
309
+ --tags "product,update"
310
+ ```
311
+
312
+ ### Merge Tags
313
+
314
+ Templates support merge tags for personalization:
315
+
316
+ - `{{first_name}}` - Contact's first name
317
+ - `{{last_name}}` - Contact's last name
318
+ - `{{email}}` - Contact's email
319
+ - `{{custom_field}}` - Any custom attribute
320
+
321
+ ### Notes
322
+
323
+ - At least one content type (HTML or text) required
324
+ - Both HTML and text recommended for best deliverability
325
+ - Subject line is optional but recommended
326
+ - Tags help organize and filter templates
327
+ - HTML content should include full document structure
328
+ - Merge tags replaced when sending campaign
329
+
330
+ ### Related Commands
331
+
332
+ - [templates get](#templates-get) - View created template
333
+ - [templates render](#templates-render) - Preview template
334
+ - [campaigns create](/en/cli/command-reference/campaigns#campaigns-create) - Use template
335
+
336
+ ---
337
+
338
+ ## templates update
339
+
340
+ Update an existing template's content or metadata.
341
+
342
+ ### Usage
343
+
344
+ ```bash
345
+ cakemail templates update <id> [options]
346
+ ```
347
+
348
+ ### Arguments
349
+
350
+ - `id` - Template ID (required)
351
+
352
+ ### Options
353
+
354
+ - `-n, --name <name>` - New template name
355
+ - `--html <html>` - New HTML content (inline)
356
+ - `--html-file <path>` - Path to new HTML file
357
+ - `--text <text>` - New plain text content (inline)
358
+ - `--text-file <path>` - Path to new text file
359
+ - `--subject <subject>` - New default subject
360
+ - `--tags <tags>` - New comma-separated tags (replaces existing)
361
+
362
+ ### Examples
363
+
364
+ **Update template name:**
365
+
366
+ ```bash
367
+ $ cakemail templates update 201 -n "Monthly Newsletter Template"
368
+ ```
369
+
370
+ **Output:**
371
+ ```
372
+ ✓ Template 201 updated
373
+ {
374
+ "id": 201,
375
+ "name": "Monthly Newsletter Template"
376
+ }
377
+ ```
378
+
379
+ **Update HTML content from file:**
380
+
381
+ ```bash
382
+ $ cakemail templates update 201 --html-file ./templates/newsletter-v2.html
383
+ ```
384
+
385
+ **Output:**
386
+ ```
387
+ ✓ Template 201 updated
388
+ ```
389
+
390
+ **Update subject line:**
391
+
392
+ ```bash
393
+ $ cakemail templates update 201 --subject "{{month}} Newsletter - Special Edition"
394
+ ```
395
+
396
+ **Update tags:**
397
+
398
+ ```bash
399
+ $ cakemail templates update 201 --tags "newsletter,monthly,featured"
400
+ ```
401
+
402
+ **Update multiple fields:**
403
+
404
+ ```bash
405
+ $ cakemail templates update 201 \
406
+ -n "Premium Newsletter" \
407
+ --html-file ./premium-newsletter.html \
408
+ --text-file ./premium-newsletter.txt \
409
+ --subject "Premium: {{month}} Newsletter" \
410
+ --tags "premium,newsletter"
411
+ ```
412
+
413
+ **Update only HTML (keep text):**
414
+
415
+ ```bash
416
+ $ cakemail templates update 201 --html-file ./new-design.html
417
+ ```
418
+
419
+ **Update inline content:**
420
+
421
+ ```bash
422
+ $ cakemail templates update 202 \
423
+ --html "<h1>Updated Offer!</h1><p>Save 30% now.</p>"
424
+ ```
425
+
426
+ ### Notes
427
+
428
+ - Only provided fields are updated (partial updates)
429
+ - Tags are replaced entirely (not merged)
430
+ - File paths must point to valid accessible files
431
+ - Changes apply to future campaign uses (not retroactive)
432
+ - Template ID remains the same
433
+
434
+ ### Related Commands
435
+
436
+ - [templates get](#templates-get) - View current template
437
+ - [templates render](#templates-render) - Preview changes
438
+ - [templates create](#templates-create) - Create new template
439
+
440
+ ---
441
+
442
+ ## templates render
443
+
444
+ Preview/render a template to see how it will appear.
445
+
446
+ ### Usage
447
+
448
+ ```bash
449
+ cakemail templates render <id>
450
+ ```
451
+
452
+ ### Arguments
453
+
454
+ - `id` - Template ID (required)
455
+
456
+ ### Examples
457
+
458
+ **Render template:**
459
+
460
+ ```bash
461
+ $ cakemail templates render 201
462
+ ```
463
+
464
+ **Output:**
465
+ ```
466
+ {
467
+ "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>",
468
+ "text": "Welcome!\n\nThis is your newsletter.",
469
+ "subject": "Monthly Newsletter"
470
+ }
471
+ ```
472
+
473
+ **Save rendered HTML to file:**
474
+
475
+ ```bash
476
+ $ cakemail templates render 201 -f json | jq -r '.html' > preview.html
477
+ ```
478
+
479
+ **Open rendered HTML in browser:**
480
+
481
+ ```bash
482
+ $ cakemail templates render 201 -f json | jq -r '.html' > preview.html && open preview.html
483
+ ```
484
+
485
+ **View rendered text version:**
486
+
487
+ ```bash
488
+ $ cakemail templates render 201 -f json | jq -r '.text'
489
+ ```
490
+
491
+ **Output:**
492
+ ```
493
+ Welcome!
494
+
495
+ This is your newsletter.
496
+ ```
497
+
498
+ **Check rendered subject:**
499
+
500
+ ```bash
501
+ $ cakemail templates render 201 -f json | jq -r '.subject'
502
+ ```
503
+
504
+ **Output:**
505
+ ```
506
+ Monthly Newsletter
507
+ ```
508
+
509
+ ### Notes
510
+
511
+ - Shows how template will appear when sent
512
+ - Merge tags shown as-is (not replaced with data)
513
+ - Use to verify template design before sending
514
+ - Useful for testing template changes
515
+ - No emails sent (preview only)
516
+
517
+ ### Related Commands
518
+
519
+ - [templates get](#templates-get) - View template source
520
+ - [templates update](#templates-update) - Modify template
521
+ - [campaigns test](/en/cli/command-reference/campaigns#campaigns-test) - Send test with data
522
+
523
+ ---
524
+
525
+ ## templates delete
526
+
527
+ Permanently delete a template.
528
+
529
+ ### Usage
530
+
531
+ ```bash
532
+ cakemail templates delete <id> [options]
533
+ ```
534
+
535
+ ### Arguments
536
+
537
+ - `id` - Template ID (required)
538
+
539
+ ### Options
540
+
541
+ - `-f, --force` - Skip confirmation prompt (use in scripts)
542
+
543
+ ### Examples
544
+
545
+ **Delete template with confirmation:**
546
+
547
+ ```bash
548
+ $ cakemail templates delete 203
549
+ ```
550
+
551
+ **Output:**
552
+ ```
553
+ ⚠ Delete template 203?
554
+
555
+ The following will happen:
556
+ • Template will be permanently deleted
557
+ • Any campaigns using this template may be affected
558
+
559
+ Type 'yes' to confirm: yes
560
+
561
+ ✓ Template 203 deleted
562
+ ```
563
+
564
+ **Force delete without confirmation:**
565
+
566
+ ```bash
567
+ $ cakemail templates delete 203 --force
568
+ ```
569
+
570
+ **Output:**
571
+ ```
572
+ ✓ Template 203 deleted
573
+ ```
574
+
575
+ **Delete in script:**
576
+
577
+ ```bash
578
+ $ cakemail templates delete 203 --force --batch
579
+ ```
580
+
581
+ ### Notes
582
+
583
+ - Deletion is permanent and cannot be undone
584
+ - Historical campaigns using template remain intact
585
+ - Future campaigns cannot use deleted template
586
+ - Template content cannot be recovered
587
+ - Confirmation required unless `--force` is used
588
+
589
+ ### Related Commands
590
+
591
+ - [templates list](#templates-list) - View templates before deletion
592
+ - [templates get](#templates-get) - Review template before deleting
593
+
594
+ ---
595
+
596
+ ## Common Workflows
597
+
598
+ ### Workflow 1: Create Template from Files
599
+
600
+ ```bash
601
+ # Prepare HTML and text files
602
+ # templates/newsletter.html
603
+ # templates/newsletter.txt
604
+
605
+ # Create template
606
+ $ cakemail templates create \
607
+ -n "March Newsletter" \
608
+ --html-file ./templates/newsletter.html \
609
+ --text-file ./templates/newsletter.txt \
610
+ --subject "{{month}} Newsletter" \
611
+ --tags "newsletter,monthly"
612
+
613
+ # Note template ID (e.g., 201)
614
+
615
+ # Preview template
616
+ $ cakemail templates render 201 -f json | jq -r '.html' > preview.html
617
+ $ open preview.html
618
+
619
+ # Use in campaign
620
+ $ cakemail campaigns create \
621
+ -n "March Newsletter Campaign" \
622
+ -l 123 \
623
+ -s 101 \
624
+ --template 201
625
+ ```
626
+
627
+ ### Workflow 2: Update Existing Template
628
+
629
+ ```bash
630
+ # Get current template
631
+ $ cakemail templates get 201
632
+
633
+ # Make changes to local files
634
+ # Edit: templates/newsletter-v2.html
635
+
636
+ # Update template
637
+ $ cakemail templates update 201 --html-file ./templates/newsletter-v2.html
638
+
639
+ # Preview changes
640
+ $ cakemail templates render 201 -f json | jq -r '.html' > preview-v2.html
641
+ $ open preview-v2.html
642
+ ```
643
+
644
+ ### Workflow 3: Template Organization
645
+
646
+ ```bash
647
+ # List all templates
648
+ $ cakemail templates list
649
+
650
+ # Add tags to organize
651
+ $ cakemail templates update 201 --tags "newsletter,active"
652
+ $ cakemail templates update 202 --tags "promo,seasonal"
653
+ $ cakemail templates update 203 --tags "onboarding,automated"
654
+
655
+ # Find templates by tag
656
+ $ cakemail templates list -f json | jq '.data[] | select(.tags[] | contains("newsletter"))'
657
+ ```
658
+
659
+ ### Workflow 4: Template Testing
660
+
661
+ ```bash
662
+ # Create test template
663
+ $ cakemail templates create \
664
+ -n "Test Design" \
665
+ --html-file ./test-design.html \
666
+ --tags "test"
667
+
668
+ # Render preview
669
+ $ cakemail templates render 204 -f json | jq -r '.html' > test.html
670
+
671
+ # Review in browser
672
+ $ open test.html
673
+
674
+ # If good, update production template
675
+ $ cakemail templates update 201 --html-file ./test-design.html
676
+
677
+ # Delete test template
678
+ $ cakemail templates delete 204 --force
679
+ ```
680
+
681
+ ### Workflow 5: Template Backup
682
+
683
+ ```bash
684
+ # Export all templates
685
+ $ cakemail templates list -f json > templates-backup.json
686
+
687
+ # Extract each template's content
688
+ for id in $(jq -r '.data[].id' templates-backup.json); do
689
+ echo "Backing up template $id..."
690
+ cakemail templates get $id -f json > "backup-template-$id.json"
691
+ cakemail templates get $id -f json | jq -r '.html' > "backup-template-$id.html"
692
+ done
693
+ ```
694
+
695
+ ## Best Practices
696
+
697
+ 1. **Version Control**: Store template HTML/CSS in version control
698
+ 2. **Multipart Templates**: Always include both HTML and text versions
699
+ 3. **Test Before Use**: Preview templates before using in campaigns
700
+ 4. **Consistent Naming**: Use clear, descriptive template names
701
+ 5. **Tag Organization**: Use tags to categorize templates
702
+ 6. **Responsive Design**: Ensure HTML templates work on mobile devices
703
+ 7. **Merge Tags**: Use merge tags for personalization
704
+ 8. **Regular Cleanup**: Delete unused or outdated templates
705
+ 9. **Backup Important Templates**: Export templates regularly
706
+
707
+ ## Troubleshooting
708
+
709
+ ### Error: "Template ID not found"
710
+
711
+ Template doesn't exist or was deleted.
712
+
713
+ **Solution:**
714
+ ```bash
715
+ # List templates to find valid ID
716
+ $ cakemail templates list
717
+
718
+ # Use correct template ID
719
+ $ cakemail templates get 201
720
+ ```
721
+
722
+ ### HTML Not Rendering Correctly
723
+
724
+ CSS or HTML structure issues.
725
+
726
+ **Solution:**
727
+ ```bash
728
+ # Preview template
729
+ $ cakemail templates render 201 -f json | jq -r '.html' > test.html
730
+
731
+ # Open in browser
732
+ $ open test.html
733
+
734
+ # Check for:
735
+ # - Missing closing tags
736
+ # - Invalid CSS
737
+ # - External resource links (should be inline or absolute URLs)
738
+
739
+ # Fix and update
740
+ $ cakemail templates update 201 --html-file ./fixed-template.html
741
+ ```
742
+
743
+ ### Merge Tags Not Working
744
+
745
+ Incorrect syntax or unsupported field.
746
+
747
+ **Solution:**
748
+ ```bash
749
+ # Use double curly braces
750
+ # Correct: {{first_name}}
751
+ # Incorrect: {first_name} or $first_name
752
+
753
+ # Ensure field exists in contacts
754
+ $ cakemail contacts get 123 501 -f json | jq '.custom_attributes'
755
+
756
+ # Update template with correct tags
757
+ $ cakemail templates update 201 --subject "Hi {{first_name}}, welcome!"
758
+ ```
759
+
760
+ ### Template Too Large
761
+
762
+ HTML file size exceeds limits.
763
+
764
+ **Solution:**
765
+ ```bash
766
+ # Check file size
767
+ $ ls -lh ./templates/large-template.html
768
+
769
+ # Optimize:
770
+ # - Inline CSS instead of external stylesheets
771
+ # - Compress/minify HTML
772
+ # - Remove unnecessary whitespace
773
+ # - Optimize images (use external URLs)
774
+ # - Remove comments
775
+
776
+ # Update with optimized version
777
+ $ cakemail templates update 201 --html-file ./optimized-template.html
778
+ ```
779
+
780
+ ### Cannot Delete Template
781
+
782
+ Template may be in use by active campaigns.
783
+
784
+ **Solution:**
785
+ ```bash
786
+ # Check which campaigns use this template
787
+ $ cakemail campaigns list -f json | jq '.data[] | select(.template_id == 201)'
788
+
789
+ # Wait for campaigns to complete
790
+ # Or update campaigns to use different template
791
+
792
+ # Then delete
793
+ $ cakemail templates delete 201 --force
794
+ ```
795
+
796
+ ### Text Version Not Displaying
797
+
798
+ Text content may be missing or not provided.
799
+
800
+ **Solution:**
801
+ ```bash
802
+ # Check if template has text content
803
+ $ cakemail templates get 201 -f json | jq '.text'
804
+
805
+ # If null or missing, add text version
806
+ $ cakemail templates update 201 --text-file ./newsletter.txt
807
+
808
+ # Or generate from HTML (manual process)
809
+ $ cakemail templates get 201 -f json | jq -r '.html' | html2text > newsletter.txt
810
+ $ cakemail templates update 201 --text-file ./newsletter.txt
811
+ ```
812
+
813
+ ---
814
+
815
+ **Related Documentation:**
816
+ - [Campaigns Commands](/en/cli/command-reference/campaigns/) - Use templates in campaigns
817
+ - [Transactional Templates Commands](/en/cli/command-reference/transactional-templates/) - Templates for Email API
818
+ - [Senders Commands](/en/cli/command-reference/senders/) - Manage sender identities