@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/03-transactional-emails.md ADDED
@@ -0,0 +1,706 @@
1
+ # Transactional Emails
2
+
3
+ Learn how to send individual transactional emails using the Cakemail Email API v2.
4
+
5
+ ## Overview
6
+
7
+ Transactional emails are one-to-one messages triggered by user actions or system events. Unlike campaigns (which go to many recipients), transactional emails are sent to individual recipients in real-time.
8
+
9
+ **Common use cases:**
10
+ - Welcome emails
11
+ - Password reset notifications
12
+ - Order confirmations
13
+ - Shipping updates
14
+ - Account alerts
15
+ - Invoice receipts
16
+ - Verification codes
17
+
18
+ ## Prerequisites
19
+
20
+ Before sending transactional emails, you need:
21
+
22
+ 1. **Verified sender email** - See [Senders](/en/cli/command-reference/senders/)
23
+ 2. **Valid authentication** - See [Authentication](/en/cli/getting-started/authentication/)
24
+
25
+ ---
26
+
27
+ ## Send Command
28
+
29
+ The `emails send` command submits a transactional email.
30
+
31
+ ### Basic Syntax
32
+
33
+ ```bash
34
+ cakemail emails send \
35
+ -t <recipient@example.com> \
36
+ -s "Email Subject" \
37
+ [content options] \
38
+ [additional options]
39
+ ```
40
+
41
+ ### Required Options
42
+
43
+ - `-t, --to <email>` - Recipient email address
44
+ - `-s, --subject <subject>` - Email subject line
45
+
46
+ **Plus one of:**
47
+ - `--html <html>` or `--html-file <path>` - HTML content
48
+ - `--text <text>` or `--text-file <path>` - Plain text content
49
+ - `--template-id <id>` - Use existing template
50
+
51
+ ---
52
+
53
+ ## Sending with HTML Content
54
+
55
+ ### Inline HTML
56
+
57
+ Send HTML content directly in the command:
58
+
59
+ ```bash
60
+ cakemail emails send \
61
+ -t recipient@example.com \
62
+ -s "Welcome to Acme Inc" \
63
+ --html "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
64
+ ```
65
+
66
+ **Best for:**
67
+ - Simple emails
68
+ - Quick tests
69
+ - Short content
70
+
71
+ ### HTML from File
72
+
73
+ Load HTML from a file (recommended for complex emails):
74
+
75
+ ```bash
76
+ cakemail emails send \
77
+ -t recipient@example.com \
78
+ -s "Welcome to Acme Inc" \
79
+ --html-file templates/welcome.html
80
+ ```
81
+
82
+ **Best for:**
83
+ - Complex HTML templates
84
+ - Reusable templates
85
+ - Version-controlled content
86
+
87
+ **Example HTML file:**
88
+ ```html
89
+ <!-- templates/welcome.html -->
90
+ <!DOCTYPE html>
91
+ <html>
92
+ <head>
93
+ <meta charset="utf-8">
94
+ <style>
95
+ body { font-family: Arial, sans-serif; }
96
+ .header { background: #007bff; color: white; padding: 20px; }
97
+ .content { padding: 20px; }
98
+ </style>
99
+ </head>
100
+ <body>
101
+ <div class="header">
102
+ <h1>Welcome to Acme Inc!</h1>
103
+ </div>
104
+ <div class="content">
105
+ <p>Hi there,</p>
106
+ <p>Thanks for signing up. We're excited to have you on board.</p>
107
+ <p><a href="https://example.com/get-started">Get Started</a></p>
108
+ </div>
109
+ </body>
110
+ </html>
111
+ ```
112
+
113
+ ---
114
+
115
+ ## Sending with Plain Text
116
+
117
+ ### Inline Text
118
+
119
+ ```bash
120
+ cakemail emails send \
121
+ -t recipient@example.com \
122
+ -s "Welcome to Acme Inc" \
123
+ --text "Thanks for signing up!"
124
+ ```
125
+
126
+ ### Text from File
127
+
128
+ ```bash
129
+ cakemail emails send \
130
+ -t recipient@example.com \
131
+ -s "Welcome to Acme Inc" \
132
+ --text-file templates/welcome.txt
133
+ ```
134
+
135
+ **Example text file:**
136
+ ```text
137
+ Welcome to Acme Inc!
138
+
139
+ Thanks for signing up. We're excited to have you on board.
140
+
141
+ Get started: https://example.com/get-started
142
+
143
+ --
144
+ Acme Inc Team
145
+ ```
146
+
147
+ ---
148
+
149
+ ## Sending with HTML and Text
150
+
151
+ Provide both HTML and plain text (recommended):
152
+
153
+ ```bash
154
+ cakemail emails send \
155
+ -t recipient@example.com \
156
+ -s "Welcome to Acme Inc" \
157
+ --html-file templates/welcome.html \
158
+ --text-file templates/welcome.txt
159
+ ```
160
+
161
+ **Why both?**
162
+ - **HTML** - Rich formatting for modern email clients
163
+ - **Plain text** - Fallback for text-only clients
164
+ - **Accessibility** - Better for screen readers
165
+ - **Spam filters** - Improves deliverability
166
+
167
+ ---
168
+
169
+ ## Using Templates
170
+
171
+ Send emails using pre-created templates with variable substitution.
172
+
173
+ ### Basic Template Usage
174
+
175
+ ```bash
176
+ cakemail emails send \
177
+ -t recipient@example.com \
178
+ -s "Welcome {{name}}" \
179
+ --template-id 123 \
180
+ --params '{"name":"John","company":"Acme Inc"}'
181
+ ```
182
+
183
+ ### Template Parameters
184
+
185
+ The `--params` option accepts JSON with variables to substitute:
186
+
187
+ ```bash
188
+ --params '{"name":"John","email":"john@example.com","orderNumber":"12345"}'
189
+ ```
190
+
191
+ **Template variables** use double curly braces: `{{variable}}`
192
+
193
+ **Example template:**
194
+ ```html
195
+ <h1>Hi {{name}},</h1>
196
+ <p>Your order {{orderNumber}} has shipped.</p>
197
+ <p>Track it here: <a href="{{trackingUrl}}">{{trackingUrl}}</a></p>
198
+ ```
199
+
200
+ **Send command:**
201
+ ```bash
202
+ cakemail emails send \
203
+ -t {{email}} \
204
+ -s "Order {{orderNumber}} Shipped" \
205
+ --template-id 456 \
206
+ --params '{
207
+ "name":"John",
208
+ "email":"john@example.com",
209
+ "orderNumber":"ORD-12345",
210
+ "trackingUrl":"https://tracking.example.com/ORD-12345"
211
+ }'
212
+ ```
213
+
214
+ See [Templates](/en/cli/command-reference/templates/) for template management.
215
+
216
+ ---
217
+
218
+ ## Custom Sender
219
+
220
+ Override the default sender for specific emails:
221
+
222
+ ```bash
223
+ cakemail emails send \
224
+ -t recipient@example.com \
225
+ -s "Order Confirmation" \
226
+ --html "<h1>Your order is confirmed</h1>" \
227
+ --from-email orders@acme.com \
228
+ --from-name "Acme Orders"
229
+ ```
230
+
231
+ **Options:**
232
+ - `--from-email <email>` - Sender email address (must be verified)
233
+ - `--from-name <name>` - Sender display name
234
+ - `--reply-to <email>` - Reply-to address (optional)
235
+
236
+ **With reply-to:**
237
+ ```bash
238
+ cakemail emails send \
239
+ -t recipient@example.com \
240
+ -s "Support Ticket #12345" \
241
+ --html "<p>Your ticket has been updated.</p>" \
242
+ --from-email support@acme.com \
243
+ --from-name "Acme Support" \
244
+ --reply-to ticket-12345@support.acme.com
245
+ ```
246
+
247
+ ---
248
+
249
+ ## Email Tracking
250
+
251
+ Enable open and click tracking:
252
+
253
+ ```bash
254
+ cakemail emails send \
255
+ -t recipient@example.com \
256
+ -s "Newsletter" \
257
+ --html-file newsletter.html \
258
+ --tracking
259
+ ```
260
+
261
+ **What gets tracked:**
262
+ - **Opens** - When recipient opens the email (using tracking pixel)
263
+ - **Clicks** - When recipient clicks links (using redirect URLs)
264
+
265
+ **Tracking data available via:**
266
+ ```bash
267
+ cakemail emails get <email-id>
268
+ cakemail emails logs --status delivered
269
+ ```
270
+
271
+ See [Email Tracking](/en/cli/email-operations/email-tracking/) for details.
272
+
273
+ ---
274
+
275
+ ## Email Tags
276
+
277
+ Tag emails for organization and filtering:
278
+
279
+ ```bash
280
+ cakemail emails send \
281
+ -t recipient@example.com \
282
+ -s "Welcome Email" \
283
+ --html-file welcome.html \
284
+ --tags "welcome,onboarding,automated"
285
+ ```
286
+
287
+ **Uses for tags:**
288
+ - **Categorization** - Group similar emails
289
+ - **Filtering** - Filter logs by tag
290
+ - **Analytics** - Track performance by category
291
+ - **Automation** - Trigger workflows
292
+
293
+ **View all tags:**
294
+ ```bash
295
+ cakemail emails tags
296
+ ```
297
+
298
+ **Filter logs by tag:**
299
+ ```bash
300
+ cakemail emails logs --tag welcome
301
+ ```
302
+
303
+ ---
304
+
305
+ ## Custom Headers
306
+
307
+ Add custom email headers:
308
+
309
+ ```bash
310
+ cakemail emails send \
311
+ -t recipient@example.com \
312
+ -s "Custom Headers Example" \
313
+ --html "<p>Email with custom headers</p>" \
314
+ --headers '{"X-Custom-ID":"12345","X-Category":"transactional"}'
315
+ ```
316
+
317
+ **Common custom headers:**
318
+ - `X-Custom-ID` - Internal tracking ID
319
+ - `X-Category` - Email category
320
+ - `X-Priority` - Email priority
321
+ - `List-Unsubscribe` - Unsubscribe link
322
+
323
+ ---
324
+
325
+ ## Attachments
326
+
327
+ Attach files to emails:
328
+
329
+ ```bash
330
+ cakemail emails send \
331
+ -t recipient@example.com \
332
+ -s "Invoice #12345" \
333
+ --html "<p>Please find your invoice attached.</p>" \
334
+ --attachments '[
335
+ {
336
+ "filename":"invoice-12345.pdf",
337
+ "content":"base64-encoded-content",
338
+ "type":"application/pdf"
339
+ }
340
+ ]'
341
+ ```
342
+
343
+ **Attachment format:**
344
+ ```json
345
+ [
346
+ {
347
+ "filename": "document.pdf",
348
+ "content": "base64-encoded-data",
349
+ "type": "application/pdf"
350
+ }
351
+ ]
352
+ ```
353
+
354
+ **Encoding files to base64:**
355
+ ```bash
356
+ base64 document.pdf
357
+ ```
358
+
359
+ **In a script:**
360
+ ```bash
361
+ #!/bin/bash
362
+ ATTACHMENT=$(base64 -w 0 invoice.pdf)
363
+ cakemail emails send \
364
+ -t customer@example.com \
365
+ -s "Your Invoice" \
366
+ --html "<p>Invoice attached</p>" \
367
+ --attachments "[{\"filename\":\"invoice.pdf\",\"content\":\"$ATTACHMENT\",\"type\":\"application/pdf\"}]"
368
+ ```
369
+
370
+ ---
371
+
372
+ ## Complete Example
373
+
374
+ Send a comprehensive transactional email with all features:
375
+
376
+ ```bash
377
+ cakemail emails send \
378
+ -t john@example.com \
379
+ -s "Order #ORD-12345 Confirmed" \
380
+ --html-file templates/order-confirmation.html \
381
+ --text-file templates/order-confirmation.txt \
382
+ --from-email orders@acme.com \
383
+ --from-name "Acme Orders" \
384
+ --reply-to support@acme.com \
385
+ --tracking \
386
+ --tags "order,confirmation,automated" \
387
+ --headers '{"X-Order-ID":"ORD-12345","X-Customer-ID":"CUST-789"}' \
388
+ --attachments '[{"filename":"receipt.pdf","content":"...", "type":"application/pdf"}]'
389
+ ```
390
+
391
+ ---
392
+
393
+ ## Retrieving Email Details
394
+
395
+ Get information about a sent email:
396
+
397
+ ```bash
398
+ cakemail emails get <email-id>
399
+ ```
400
+
401
+ **Example output:**
402
+ ```json
403
+ {
404
+ "id": "abc123def456",
405
+ "to": "recipient@example.com",
406
+ "subject": "Welcome Email",
407
+ "status": "delivered",
408
+ "from": {
409
+ "email": "hello@acme.com",
410
+ "name": "Acme Inc"
411
+ },
412
+ "tracking": {
413
+ "opened": true,
414
+ "opened_at": "2024-06-15T10:30:00Z",
415
+ "clicks": 2
416
+ },
417
+ "tags": ["welcome", "onboarding"],
418
+ "created_at": "2024-06-15T10:00:00Z",
419
+ "delivered_at": "2024-06-15T10:01:00Z"
420
+ }
421
+ ```
422
+
423
+ ---
424
+
425
+ ## Rendering Email HTML
426
+
427
+ Preview the rendered HTML of a sent email:
428
+
429
+ ```bash
430
+ cakemail emails render <email-id>
431
+ ```
432
+
433
+ **With tracking enabled:**
434
+ ```bash
435
+ cakemail emails render <email-id> --tracking
436
+ ```
437
+
438
+ **As originally submitted:**
439
+ ```bash
440
+ cakemail emails render <email-id> --as-submitted
441
+ ```
442
+
443
+ **Save to file:**
444
+ ```bash
445
+ cakemail emails render <email-id> > email.html
446
+ ```
447
+
448
+ ---
449
+
450
+ ## Viewing Email Logs
451
+
452
+ Query email sending activity:
453
+
454
+ ### All Recent Emails
455
+
456
+ ```bash
457
+ cakemail emails logs --limit 50
458
+ ```
459
+
460
+ ### Filter by Date Range
461
+
462
+ ```bash
463
+ cakemail emails logs \
464
+ --from 2024-06-01 \
465
+ --to 2024-06-30
466
+ ```
467
+
468
+ ### Filter by Status
469
+
470
+ ```bash
471
+ # Delivered emails
472
+ cakemail emails logs --status delivered
473
+
474
+ # Bounced emails
475
+ cakemail emails logs --status bounced
476
+
477
+ # Failed emails
478
+ cakemail emails logs --status failed
479
+ ```
480
+
481
+ ### Filter by Tag
482
+
483
+ ```bash
484
+ cakemail emails logs --tag welcome
485
+ cakemail emails logs --tag "order-confirmation"
486
+ ```
487
+
488
+ ### Combined Filters
489
+
490
+ ```bash
491
+ cakemail emails logs \
492
+ --from 2024-06-01 \
493
+ --to 2024-06-30 \
494
+ --tag welcome \
495
+ --status delivered \
496
+ --limit 100
497
+ ```
498
+
499
+ ---
500
+
501
+ ## Practical Examples
502
+
503
+ ### Example 1: Welcome Email Script
504
+
505
+ ```bash
506
+ #!/bin/bash
507
+ # send-welcome.sh
508
+
509
+ EMAIL=$1
510
+ NAME=$2
511
+
512
+ if [ -z "$EMAIL" ] || [ -z "$NAME" ]; then
513
+ echo "Usage: ./send-welcome.sh <email> <name>"
514
+ exit 1
515
+ fi
516
+
517
+ cakemail emails send \
518
+ -t "$EMAIL" \
519
+ -s "Welcome to Acme, $NAME!" \
520
+ --template-id 123 \
521
+ --params "{\"name\":\"$NAME\",\"email\":\"$EMAIL\"}" \
522
+ --tracking \
523
+ --tags "welcome,automated"
524
+
525
+ echo "Welcome email sent to $EMAIL"
526
+ ```
527
+
528
+ **Usage:**
529
+ ```bash
530
+ ./send-welcome.sh john@example.com "John Doe"
531
+ ```
532
+
533
+ ### Example 2: Password Reset
534
+
535
+ ```bash
536
+ #!/bin/bash
537
+ # send-reset.sh
538
+
539
+ EMAIL=$1
540
+ RESET_TOKEN=$2
541
+ RESET_URL="https://example.com/reset?token=$RESET_TOKEN"
542
+
543
+ cakemail emails send \
544
+ -t "$EMAIL" \
545
+ -s "Password Reset Request" \
546
+ --html "<p>Click to reset: <a href=\"$RESET_URL\">Reset Password</a></p>" \
547
+ --from-email security@acme.com \
548
+ --from-name "Acme Security" \
549
+ --tags "security,password-reset" \
550
+ --headers "{\"X-Reset-Token\":\"$RESET_TOKEN\"}"
551
+ ```
552
+
553
+ ### Example 3: Order Confirmation with Invoice
554
+
555
+ ```bash
556
+ #!/bin/bash
557
+ # send-order-confirmation.sh
558
+
559
+ EMAIL=$1
560
+ ORDER_ID=$2
561
+ INVOICE_FILE=$3
562
+
563
+ # Encode invoice to base64
564
+ INVOICE_BASE64=$(base64 -w 0 "$INVOICE_FILE")
565
+
566
+ cakemail emails send \
567
+ -t "$EMAIL" \
568
+ -s "Order $ORDER_ID Confirmed" \
569
+ --template-id 456 \
570
+ --params "{\"orderNumber\":\"$ORDER_ID\"}" \
571
+ --tracking \
572
+ --tags "order,confirmation" \
573
+ --attachments "[{\"filename\":\"invoice-$ORDER_ID.pdf\",\"content\":\"$INVOICE_BASE64\",\"type\":\"application/pdf\"}]"
574
+ ```
575
+
576
+ ### Example 4: Bulk Transactional Emails
577
+
578
+ ```bash
579
+ #!/bin/bash
580
+ # bulk-send.sh
581
+
582
+ # Read emails from CSV file
583
+ while IFS=',' read -r EMAIL NAME; do
584
+ echo "Sending to $EMAIL..."
585
+
586
+ cakemail emails send \
587
+ -t "$EMAIL" \
588
+ -s "Monthly Newsletter" \
589
+ --template-id 789 \
590
+ --params "{\"name\":\"$NAME\"}" \
591
+ --tracking \
592
+ --tags "newsletter,monthly"
593
+
594
+ # Rate limiting
595
+ sleep 0.5
596
+ done < contacts.csv
597
+
598
+ echo "All emails sent"
599
+ ```
600
+
601
+ ---
602
+
603
+ ## Best Practices
604
+
605
+ ### 1. Always Provide Plain Text
606
+
607
+ ```bash
608
+ # ✅ Good: HTML + text
609
+ cakemail emails send \
610
+ -t user@example.com \
611
+ -s "Subject" \
612
+ --html-file email.html \
613
+ --text-file email.txt
614
+
615
+ # ❌ Avoid: HTML only
616
+ cakemail emails send \
617
+ -t user@example.com \
618
+ -s "Subject" \
619
+ --html-file email.html
620
+ ```
621
+
622
+ ### 2. Use Templates for Reusable Content
623
+
624
+ ```bash
625
+ # ✅ Good: Reusable template
626
+ cakemail emails send -t user@example.com -s "Welcome" --template-id 123
627
+
628
+ # ❌ Avoid: Hardcoded content for repeated sends
629
+ cakemail emails send -t user@example.com -s "Welcome" --html "..."
630
+ ```
631
+
632
+ ### 3. Tag Your Emails
633
+
634
+ ```bash
635
+ # ✅ Good: Organized with tags
636
+ cakemail emails send ... --tags "welcome,automated,v2"
637
+
638
+ # ❌ Avoid: No categorization
639
+ cakemail emails send ...
640
+ ```
641
+
642
+ ### 4. Use Descriptive Subjects
643
+
644
+ ```bash
645
+ # ✅ Good: Clear and specific
646
+ -s "Order #12345 Confirmed - Estimated Delivery June 20"
647
+
648
+ # ❌ Avoid: Generic
649
+ -s "Order Confirmation"
650
+ ```
651
+
652
+ ### 5. Test Before Bulk Sending
653
+
654
+ ```bash
655
+ # Test with your own email first
656
+ cakemail emails send -t your@email.com -s "Test" --html-file email.html
657
+
658
+ # Then send to recipients
659
+ ```
660
+
661
+ ---
662
+
663
+ ## Troubleshooting
664
+
665
+ ### Email Not Delivered
666
+
667
+ **Check email status:**
668
+ ```bash
669
+ cakemail emails get <email-id>
670
+ ```
671
+
672
+ **Common issues:**
673
+ 1. Unverified sender email
674
+ 2. Invalid recipient email
675
+ 3. Bounced address
676
+ 4. Spam filters
677
+
678
+ **View logs:**
679
+ ```bash
680
+ cakemail emails logs --status bounced
681
+ ```
682
+
683
+ ### Template Variables Not Substituted
684
+
685
+ **Verify params format:**
686
+ ```bash
687
+ # ✅ Correct JSON
688
+ --params '{"name":"John","age":30}'
689
+
690
+ # ❌ Invalid JSON
691
+ --params '{name:John,age:30}'
692
+ ```
693
+
694
+ ### Tracking Not Working
695
+
696
+ **Ensure tracking is enabled:**
697
+ ```bash
698
+ cakemail emails send ... --tracking
699
+ ```
700
+
701
+ **Check email client:**
702
+ - Some clients block tracking pixels
703
+ - Links must be clicked (not just hovered)
704
+
705
+ ---
706
+