senddart-cli 1.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.
- package/LICENSE +21 -0
- package/README.md +377 -0
- package/bin/senddart.js +14 -0
- package/package.json +43 -0
- package/src/cli.js +179 -0
- package/src/commands/apikeys.js +16 -0
- package/src/commands/audiences.js +46 -0
- package/src/commands/automations.js +157 -0
- package/src/commands/campaigns.js +153 -0
- package/src/commands/contact_properties.js +49 -0
- package/src/commands/contacts.js +227 -0
- package/src/commands/domains.js +175 -0
- package/src/commands/emails.js +330 -0
- package/src/commands/events.js +63 -0
- package/src/commands/logs.js +23 -0
- package/src/commands/polls.js +19 -0
- package/src/commands/segments.js +51 -0
- package/src/commands/templates.js +96 -0
- package/src/commands/topics.js +56 -0
- package/src/commands/webhooks.js +111 -0
- package/src/helpers.js +107 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 SendDart
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,377 @@
|
|
|
1
|
+
# senddart-cli
|
|
2
|
+
|
|
3
|
+
Official command-line interface for the [SendDart](https://www.senddart.com) email API. Wraps the [`senddart`](https://www.npmjs.com/package/senddart) Node.js SDK.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm i -g senddart-cli
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Requires Node.js 18+.
|
|
12
|
+
|
|
13
|
+
## Authentication
|
|
14
|
+
|
|
15
|
+
Set your API key once:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
export SENDDART_API_KEY=mb_xxxxxxxxx
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Or pass `--api-key mb_xxxxxxxxx` to any command. Use `SENDDART_BASE_URL` (or `--base-url`) to target a different API host.
|
|
22
|
+
|
|
23
|
+
## Output
|
|
24
|
+
|
|
25
|
+
Every command prints the API response as pretty-printed JSON. Pass `--json` for raw compact JSON (handy for piping to `jq`). On failure a JSON error object is printed to **stderr** and the command exits `1`; stdout stays JSON-only either way, so `senddart … | jq` never has to strip a diagnostic.
|
|
26
|
+
|
|
27
|
+
The error object is always `{ statusCode, name, message }` — branch on `name`, never on `message`:
|
|
28
|
+
|
|
29
|
+
| Where it came from | `statusCode` | `name` |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| The API rejected the request | the HTTP status | the API's reason, e.g. `validation_error`, `daily_quota_exceeded` |
|
|
32
|
+
| The request never reached the API | `0` | `network_error` |
|
|
33
|
+
| The CLI rejected your flags before sending | `null` | `cli_error` |
|
|
34
|
+
|
|
35
|
+
Some API errors are a superset of that envelope and the extra fields are printed too: `limit` on plan/quota rejections, `reputation` on a reputation gate, and `sent`/`sent_count` on a partially applied `emails batch`.
|
|
36
|
+
|
|
37
|
+
One endpoint reports failure inside a `200` body rather than as an error: `webhooks test` returns `{ ok: false, error }` when the delivery did not land. The CLI prints that body to stdout and still exits `1`, so `senddart webhooks test wh_123 && deploy` behaves as you would expect.
|
|
38
|
+
|
|
39
|
+
`--help` works at every level: `senddart --help`, `senddart emails --help`, `senddart emails send --help`.
|
|
40
|
+
|
|
41
|
+
### Pagination
|
|
42
|
+
|
|
43
|
+
List commands take `--limit` (integer `1`–`100`, default `20`) plus one of `--after` / `--before` — cursors are item ids, and passing both is rejected. Responses are `{ "object": "list", "has_more": bool, "data": [...] }`; page forward by feeding the last `data[].id` back as `--after`.
|
|
44
|
+
|
|
45
|
+
Two default page sizes exist. `domains list`, `api-keys list`, `topics list`, `contacts list`, `contacts segments`, `contacts topics`, `segments list`, `segments contacts`, `campaigns list`, `contact-properties list`, `polls list`, `emails receiving list` and `emails receiving attachments` skip the default `20` when you pass no pagination flag — but they do **not** return the whole collection: the response is capped at **1,000** rows, and `has_more` is `true` when that cap truncated it, so keep paging with `--after`. Everything else caps at 20 unless you raise `--limit`: `emails list`, `templates list`, `webhooks list`, `audiences list`, `automations list`, `automations runs`, `events list` and `logs list`.
|
|
46
|
+
|
|
47
|
+
A few endpoints are deliberately unpaginated and take no cursor flags — `emails sources`, `emails attachments`, `emails receiving addresses` and `campaigns engagement` (whose three lists are each capped at 500 rows server-side).
|
|
48
|
+
|
|
49
|
+
## Usage
|
|
50
|
+
|
|
51
|
+
### Emails
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
senddart emails send --from 'Acme <hi@yourdomain.com>' --to 'delivered@test.senddart.com' --subject 'hello' --html '<p>hi</p>'
|
|
55
|
+
senddart emails send --to 'ada@yourdomain.com,rae@yourdomain.com' \
|
|
56
|
+
--template-id tmpl_welcome --variables '{"first_name":"Ada"}' --scheduled-at 2026-08-01T09:00:00Z
|
|
57
|
+
senddart emails list --limit 20
|
|
58
|
+
senddart emails list --status delivered --search 'invoice'
|
|
59
|
+
senddart emails list --folder scheduled # mailbox folder: outbox | sent | scheduled | failed (anything else is a 422)
|
|
60
|
+
senddart emails sources # per-source metrics: one row per campaign/automation + api and individual one-off roll-ups
|
|
61
|
+
senddart emails get em_123
|
|
62
|
+
senddart emails update em_123 --scheduled-at 2026-08-02T09:00:00Z
|
|
63
|
+
senddart emails cancel em_123
|
|
64
|
+
senddart emails attachments em_123
|
|
65
|
+
senddart emails attachment em_123 att_456
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`--to`, `--cc`, `--bcc` and `--reply-to` are repeatable and accept comma-separated values.
|
|
69
|
+
|
|
70
|
+
`--from` and `--subject` are required for an ordinary send but **optional** with `--template-id` / `--template-alias`, as the two template examples in this section show: omit them and the template's own stored from and subject are used. Supply them and your values win for good — the flags are sent verbatim, so editing and republishing the template stops changing the from and subject that command sends. The body still re-renders from the template on every send; only those two fields stop tracking it. An empty value is a choice rather than an omission: `--subject ''` ships a blank subject line, and `--from ''` is rejected with `422 missing_required_field`.
|
|
71
|
+
|
|
72
|
+
`delivered@test.senddart.com` above is the mailbox simulator: it is intercepted before the provider is contacted and synthesizes the documented outcome (`bounced@`, `complained@` and `suppressed@` produce the other three; `delivered@`, `bounced@` and `complained@` also accept a `+label` suffix, `suppressed@` does not). Two things to know when you script against it — it only fires on an **immediate** send, so pairing it with a future `--scheduled-at` skips the simulator and the address is treated as suppressed (`422`); and quota is debited per recipient exactly like a real send. Documentation domains (`example.com`, `example.net`, `example.org`, anything under `.test` / `.invalid` / `.localhost` / `.example`) are blocked outright and never reach a mailbox, so do not use them as stand-in recipients.
|
|
73
|
+
|
|
74
|
+
Attach files with `--attachment <path>` (read and base64-encoded locally) or `--attachment-url <url>` (fetched server-side). Both are repeatable; the API caps an attachment at 25 MB and a message at 40 MB decoded, and the CLI checks local files against those limits before sending.
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
senddart emails send --from hi@yourdomain.com --to delivered@test.senddart.com --subject 'Your invoice' \
|
|
78
|
+
--text 'Attached.' --attachment ./invoice.pdf
|
|
79
|
+
senddart emails send --to delivered@test.senddart.com \
|
|
80
|
+
--template-alias welcome --variables '{"first_name":"Ada"}'
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`--idempotency-key` accepts **1–255 characters**, measured after the server trims the value — 255, not 256 — and is honoured by `emails send`, `emails batch`, `emails receiving reply`, and `emails receiving forward`. The CLI sends the key verbatim and lets the server be the authority: an out-of-range key comes back as `400 invalid_idempotency_key`. Reusing a key with a different body is rejected (`409 invalid_idempotent_request`); replaying it with the same body returns the original response instead of sending twice. Every other command ignores the header, so a retry there creates a second resource.
|
|
84
|
+
|
|
85
|
+
Batch-send up to 100 emails in one request from a JSON file (an array of send payloads) or inline JSON:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
senddart emails batch --file ./batch.json
|
|
89
|
+
senddart emails batch --data '[{"from":"hi@yourdomain.com","to":["delivered@test.senddart.com"],"subject":"hi","text":"hello"}]'
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Received (inbound) email
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
senddart emails receiving list --limit 20
|
|
96
|
+
senddart emails receiving addresses # per-address inbound stats
|
|
97
|
+
senddart emails receiving get rem_123
|
|
98
|
+
senddart emails receiving attachments rem_123
|
|
99
|
+
senddart emails receiving attachment rem_123 att_456 --output invoice.pdf # default filename: the attachment id
|
|
100
|
+
senddart emails receiving raw rem_123 --output message.eml # default filename: <id>.eml
|
|
101
|
+
senddart emails receiving forward rem_123 --from you@yourdomain.com --to delivered@test.senddart.com
|
|
102
|
+
senddart emails receiving reply rem_123 --from you@yourdomain.com --html '<p>thanks!</p>'
|
|
103
|
+
senddart emails receiving delete rem_123
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`attachment` and `raw` download binary content: the file is written to `--output` (or the default filename) and the CLI prints where it was saved. `reply` requires at least one of `--html` / `--text`.
|
|
107
|
+
|
|
108
|
+
### Domains
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
senddart domains add yourdomain.com
|
|
112
|
+
senddart domains list
|
|
113
|
+
senddart domains get dom_123
|
|
114
|
+
senddart domains verify dom_123
|
|
115
|
+
senddart domains update dom_123 --click-tracking --tls enforced
|
|
116
|
+
senddart domains update dom_123 --custom-return-path mail --receiving
|
|
117
|
+
senddart domains mx-check yourdomain.com
|
|
118
|
+
senddart domains records-csv dom_123 --output dns.csv # default filename: <id>-dns-records.csv
|
|
119
|
+
senddart domains delete dom_123
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`records-csv` answers `text/csv`, not JSON, so the CLI writes it to `--output` (or the default filename) and prints where it landed — the same shape as the `emails receiving` binary downloads.
|
|
123
|
+
|
|
124
|
+
One-click DNS — detect the provider, then apply the records via its API (auto-verifies after):
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
senddart domains dns detect dom_123
|
|
128
|
+
senddart domains dns cloudflare dom_123 --token cf_api_token
|
|
129
|
+
senddart domains dns godaddy dom_123 --key gd_key --secret gd_secret
|
|
130
|
+
senddart domains dns namecheap dom_123 --api-user ncuser --key nc_api_key
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Claim a domain already verified by another account (start the claim, add the TXT record it returns, then verify):
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
senddart domains claim start yourdomain.com
|
|
137
|
+
senddart domains claim get dom_123
|
|
138
|
+
senddart domains claim verify dom_123
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Contacts (domain-first)
|
|
142
|
+
|
|
143
|
+
Each sending domain has its own contact pool, so `contacts create` and `contacts list` need to be told which container to use — exactly one of `--domain <domain>` or `--audience-id <id>`; passing neither, or both, is a usage error:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
senddart contacts create --domain yourdomain.com --email ada@yourdomain.com --first-name Ada
|
|
147
|
+
senddart contacts list --domain yourdomain.com
|
|
148
|
+
senddart contacts list --domain yourdomain.com --segment-id seg_123
|
|
149
|
+
senddart contacts list --audience-id aud_123 # plain audiences instead of a domain pool
|
|
150
|
+
senddart contacts get ada@yourdomain.com --domain yourdomain.com # or by contact id, no --domain needed
|
|
151
|
+
senddart contacts update con_123 --unsubscribed
|
|
152
|
+
senddart contacts add-to-segment con_123 seg_123
|
|
153
|
+
senddart contacts remove-from-segment con_123 seg_123
|
|
154
|
+
senddart contacts topics con_123
|
|
155
|
+
senddart contacts set-topics con_123 --topics '[{"id":"top_123","subscription":"opt_out"}]'
|
|
156
|
+
senddart contacts delete con_123
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Bulk-import a CSV. Files up to 5 MB / 10,000 rows go inline with `--csv`; anything larger is uploaded directly to storage first — mint a presigned URL, `PUT` the file to it, then finish the import with the `storage_key` it returned:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
senddart contacts import aud_123 --csv ./contacts.csv --segment-id seg_123
|
|
163
|
+
senddart contacts import-upload aud_123 --csv ./big-list.csv # → { storage_key, upload_url, max_bytes, ... }
|
|
164
|
+
curl -X PUT --upload-file ./big-list.csv "$UPLOAD_URL"
|
|
165
|
+
senddart contacts import aud_123 --storage-key "$STORAGE_KEY"
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
`import` takes exactly one of `--csv` / `--storage-key`. The `upload_url` is a short-lived bearer credential — don't log it or paste it into a shared shell history.
|
|
169
|
+
|
|
170
|
+
When the source is already structured, `contacts batch` imports a JSON array instead of a CSV (upsert by email, max 10,000 per call, exactly one of `--file` / `--data`):
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
senddart contacts batch aud_123 --file ./contacts.json # audience as the positional…
|
|
174
|
+
senddart contacts batch --audience-id aud_123 --file ./contacts.json # …or as the flag, like every other contacts command
|
|
175
|
+
senddart contacts batch aud_123 --data '[{"email":"ada@yourdomain.com","first_name":"Ada"}]' --on-conflict skip
|
|
176
|
+
# Domain-first: import straight into a domain's pool, no audience id needed.
|
|
177
|
+
senddart contacts batch --domain yourdomain.com --file ./contacts.json
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Contact properties & audiences
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
senddart contact-properties create --key company --type string --fallback-value 'your company'
|
|
184
|
+
senddart contact-properties list
|
|
185
|
+
senddart contact-properties update prop_123 --fallback-value 'n/a'
|
|
186
|
+
senddart contact-properties update prop_123 --clear-fallback
|
|
187
|
+
senddart contact-properties delete prop_123
|
|
188
|
+
|
|
189
|
+
senddart audiences create --name Newsletter
|
|
190
|
+
senddart audiences list
|
|
191
|
+
senddart audiences update aud_123 --name 'Newsletter EU'
|
|
192
|
+
senddart audiences import-sheet aud_123 --url 'https://docs.google.com/spreadsheets/d/...' --segment-name 'July leads'
|
|
193
|
+
senddart audiences delete aud_123
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Segments & topics
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
senddart segments create --domain yourdomain.com --name VIP
|
|
200
|
+
senddart segments create --domain yourdomain.com --name Actives --filter '{"status":"subscribed"}'
|
|
201
|
+
senddart segments list --domain yourdomain.com
|
|
202
|
+
senddart segments contacts seg_123
|
|
203
|
+
|
|
204
|
+
senddart topics create --domain yourdomain.com --name 'Product updates' --default-subscription opt_in
|
|
205
|
+
senddart topics list --domain yourdomain.com
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Campaigns
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
senddart campaigns create --domain yourdomain.com --from 'Acme <hi@yourdomain.com>' \
|
|
212
|
+
--subject 'Summer sale' --html '<p>50% off</p>' --segment-id seg_123
|
|
213
|
+
senddart campaigns create --domain yourdomain.com --from 'Acme <hi@yourdomain.com>' \
|
|
214
|
+
--subject 'Weekly digest' --html '<p>...</p>' --recurrence weekly --unsubscribe-policy domain \
|
|
215
|
+
--followups '[{"condition":"not_opened","delay":"2 days","html":"<p>Did you see this?</p>"}]'
|
|
216
|
+
senddart campaigns send camp_123
|
|
217
|
+
senddart campaigns send camp_123 --scheduled-at 2026-08-01T09:00:00Z
|
|
218
|
+
senddart campaigns send camp_123 --scheduled-at 'in 1 min'
|
|
219
|
+
senddart campaigns stats camp_123
|
|
220
|
+
senddart campaigns engagement camp_123 # who opened, clicked and replied (each list capped at 500 rows)
|
|
221
|
+
senddart campaigns ab camp_123
|
|
222
|
+
senddart campaigns cancel camp_123
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Templates
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
senddart templates create --name Welcome --subject 'Hi {{first_name}}' --html '<p>Welcome!</p>'
|
|
229
|
+
senddart templates list
|
|
230
|
+
senddart templates duplicate tmpl_123 --name 'Welcome v2'
|
|
231
|
+
senddart templates publish tmpl_123
|
|
232
|
+
|
|
233
|
+
# Declare the variables the template uses, with their types and fallbacks
|
|
234
|
+
senddart templates update tmpl_123 \
|
|
235
|
+
--variables '[{"key":"first_name","type":"string","fallback_value":"there"},{"key":"seats","type":"number","fallback_value":1}]'
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
`--variables` is the template's declared-variable registry, not the per-send values: a JSON array of `{"key","type"?,"fallback_value"?}` (max 50 entries; `type` is `string` or `number`, and a `number` fallback must parse as a number). A send prefers a declared fallback when the caller omits that variable, so a template with no registry has no fallbacks. Pass `[]` to clear it. Edits land on the draft — `templates publish` makes them live.
|
|
239
|
+
|
|
240
|
+
### Automations & events
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
senddart automations create --name 'Welcome series' --domain yourdomain.com --trigger contact.created
|
|
244
|
+
senddart automations add-step auto_123 --type send_email --config '{"template_id":"tmpl_welcome"}'
|
|
245
|
+
senddart automations update-step auto_123 step_456 --type wait_for_event --config '{"event":"email.opened","timeout":"12 hours"}'
|
|
246
|
+
senddart automations delete-step auto_123 step_456
|
|
247
|
+
senddart automations update auto_123 --status enabled
|
|
248
|
+
|
|
249
|
+
# update-step replaces the step outright, so --type is required and --config is
|
|
250
|
+
# the complete new config. A step's graph key is immutable — delete and re-add
|
|
251
|
+
# with `add-step --key` to re-key it.
|
|
252
|
+
senddart automations runs auto_123
|
|
253
|
+
senddart automations runs auto_123 --status failed,skipped # filtered before paging; repeatable
|
|
254
|
+
senddart automations run auto_123 run_456
|
|
255
|
+
senddart automations stop auto_123
|
|
256
|
+
|
|
257
|
+
# Author (or extend) the step graph from a prompt — the automation must be stopped, and this spends AI credits
|
|
258
|
+
senddart automations ai auto_123 --prompt 'Welcome new signups, then nudge anyone who has not opened after 2 days'
|
|
259
|
+
senddart automations ai auto_123 --prompt 'Send the upgrade nudge' --attach-from step_3 --attach-type condition_met
|
|
260
|
+
|
|
261
|
+
# Fire a custom event — only yourdomain.com's automations are triggered
|
|
262
|
+
senddart events send --domain yourdomain.com --name signup.completed --email ada@yourdomain.com --data '{"plan":"pro"}'
|
|
263
|
+
senddart events list
|
|
264
|
+
senddart events create --name signup.completed --schema '{"plan":"string"}'
|
|
265
|
+
senddart events update evt_123 --schema '{"plan":"string","seats":"number"}' # the name is immutable
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### Webhooks, API keys, logs, polls
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
senddart webhooks create --endpoint https://yourapp.com/hooks --events email.delivered,email.bounced
|
|
272
|
+
senddart webhooks rotate wh_123
|
|
273
|
+
senddart webhooks test wh_123
|
|
274
|
+
senddart webhooks verify --secret whsec_xxx --payload-file ./delivery.json \
|
|
275
|
+
--svix-id msg_123 --svix-timestamp 1754000000 --svix-signature 'v1,base64sig'
|
|
276
|
+
|
|
277
|
+
senddart api-keys list
|
|
278
|
+
|
|
279
|
+
senddart logs list --limit 100 --method POST --status 429
|
|
280
|
+
senddart logs get log_123
|
|
281
|
+
|
|
282
|
+
senddart polls list
|
|
283
|
+
senddart polls get em_123
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
`webhooks verify` is the only command that makes no HTTP request: it recomputes the delivery signature locally and prints `{ valid, reason }`. It is also the only command that needs **no API key** — it never contacts the API, so a webhook receiver can run it without holding a send-capable key. Pass the **exact raw body bytes** your endpoint received via `--payload` or `--payload-file` — re-serialized JSON will not match. `--tolerance <seconds>` caps timestamp skew (default `300`; `0` skips the freshness check). Note the exit code is `0` whenever the check ran, whatever the verdict — branch on `.valid`, not on `$?` (unlike `webhooks test`, which exits `1` on a failed delivery).
|
|
287
|
+
|
|
288
|
+
#### API keys are read-only from the CLI
|
|
289
|
+
|
|
290
|
+
`api-keys list` is the whole group. There is no `create`, `update` or `delete`, and that is deliberate: **keys are created, re-scoped and revoked in the [SendDart dashboard](https://www.senddart.com/app/api-keys)**, behind a signed-in session.
|
|
291
|
+
|
|
292
|
+
Every CLI invocation authenticates with an API key, so keeping key lifecycle out of the CLI means a key that leaks — from a shell history, a CI log, a `.env` someone pasted — cannot mint itself a replacement, widen its own permission or domain scope, or revoke the keys around it. Its blast radius stays fixed at what it could already do. The API enforces the same rule: `POST /api-keys`, `PATCH /api-keys/:id` and `DELETE /api-keys/:id` answer `403 dashboard_only` to any API-key caller.
|
|
293
|
+
|
|
294
|
+
`api-keys list` still shows everything you need to audit: each key's non-secret prefix, permission, domain scoping and `last_used_at`.
|
|
295
|
+
|
|
296
|
+
## Command names vs. SDK method names
|
|
297
|
+
|
|
298
|
+
The CLI's verbs are deliberately shorter than the corresponding SDK methods. A
|
|
299
|
+
subcommand is already scoped by its resource path, so the CLI names every list
|
|
300
|
+
after its plural noun and every download after the thing downloaded:
|
|
301
|
+
|
|
302
|
+
| CLI command | SDK method (`senddart` npm naming) |
|
|
303
|
+
|---|---|
|
|
304
|
+
| `emails attachments <id>` | `emails.listAttachments` |
|
|
305
|
+
| `emails receiving addresses` | `emails.receiving.listAddresses` |
|
|
306
|
+
| `emails receiving attachments <id>` | `emails.receiving.listAttachments` |
|
|
307
|
+
| `emails receiving raw <id>` | `emails.receiving.getRaw` |
|
|
308
|
+
| `automations ai <id>` | `automations.createWithAi` |
|
|
309
|
+
| `contacts import-upload <audienceId>` | `contacts.createImportUpload` |
|
|
310
|
+
|
|
311
|
+
This is a shell-surface convention, not drift: the CLI applies the same
|
|
312
|
+
shortening rule to every endpoint rather than to some.
|
|
313
|
+
|
|
314
|
+
The right-hand column is the Node.js SDK's spelling, because that is the library
|
|
315
|
+
this CLI calls. Seven of the eight client libraries put the same method on the
|
|
316
|
+
same nested resource and differ only in each language's casing and accessor
|
|
317
|
+
syntax — `listAttachments` in npm, PHP (`$senddart->emails->receiving`) and
|
|
318
|
+
Java (`emails().receiving()`), `list_attachments` in Python, Ruby and Rust,
|
|
319
|
+
`ListAttachments` in Go (`client.Emails.Receiving`). The .NET SDK is the
|
|
320
|
+
exception: it is a flat client, so read `EmailListAttachmentsAsync`,
|
|
321
|
+
`ReceivedEmailListAddressesAsync`, `ReceivedEmailListAttachmentsAsync`,
|
|
322
|
+
`ReceivedEmailGetRawAsync`, `AutomationCreateWithAiAsync` and
|
|
323
|
+
`ContactImportCreateUploadAsync` instead of the dotted names above.
|
|
324
|
+
|
|
325
|
+
## Documentation
|
|
326
|
+
|
|
327
|
+
Full API docs: <https://www.senddart.com/docs>
|
|
328
|
+
|
|
329
|
+
## License
|
|
330
|
+
|
|
331
|
+
MIT
|
|
332
|
+
|
|
333
|
+
## Recovery and tracking contracts
|
|
334
|
+
|
|
335
|
+
Use a stable, unique operation key for each intended send, batch, reply, or
|
|
336
|
+
forward. Keep the same key and payload when recovering that operation. These
|
|
337
|
+
are the supported idempotent send endpoints; events do not implement this
|
|
338
|
+
header. Existing calls without options still work.
|
|
339
|
+
|
|
340
|
+
```sh
|
|
341
|
+
senddart emails receiving reply rem_123 --from me@yourdomain.com --text "Thanks" --idempotency-key reply-operation-1
|
|
342
|
+
senddart emails receiving forward rem_123 --from me@yourdomain.com --to team@yourdomain.com --idempotency-key forward-operation-1
|
|
343
|
+
senddart domains tracking-health dom_123
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Automatic retries consider only 429/503. They stop on an original email `id`,
|
|
347
|
+
positive `sent_count`, nonempty `sent` or `reserved`, or `batch_incomplete`.
|
|
348
|
+
An ordinary rate limit can retry; a generic 503 can retry a read or a send with
|
|
349
|
+
the same supported key. Other writes retry only documented pre-processing
|
|
350
|
+
rejections (`service_unavailable`, `sending_service_unavailable`,
|
|
351
|
+
`sending_configuration_unavailable`, `contacts_busy`, `contacts_timeout`).
|
|
352
|
+
No network/body-read failure, 409, 422, or other 5xx is retried automatically.
|
|
353
|
+
The default transport refuses redirects; a custom transport/client must enforce
|
|
354
|
+
its own policy.
|
|
355
|
+
|
|
356
|
+
On a failed or unconfirmed send, inspect `id` with the email retrieval method
|
|
357
|
+
before creating another send. A 422 with an ID can identify an uncertain
|
|
358
|
+
provider handoff; 422 does not always mean nothing happened. For interrupted
|
|
359
|
+
batches, `sent` contains confirmed sends, `reserved` contains the original
|
|
360
|
+
attempted prefix (including uncertain handoffs), and `unsent_count` counts the
|
|
361
|
+
never-attempted tail. Do not resend the full batch or the reserved prefix under
|
|
362
|
+
a new key. Reconcile original IDs first, then submit only known unattempted
|
|
363
|
+
items as a new operation. Recovery fields remain available in the full error
|
|
364
|
+
body as well as language-specific fields/accessors.
|
|
365
|
+
|
|
366
|
+
Tracking health returns `custom_host`, `status` (`shared`, `ready`, or
|
|
367
|
+
`unavailable`), and `checked_at`. Configure custom tracking through the domain
|
|
368
|
+
API and check health before relying on it. A healthy endpoint cannot guarantee
|
|
369
|
+
an open event: recipients may block images, and coupon redemption alone is not
|
|
370
|
+
proof that the tracking pixel loaded. SDKs preserve supplied HTML/text and do
|
|
371
|
+
not infer opens or rewrite editor spacing.
|
|
372
|
+
|
|
373
|
+
Campaign cancellation also stops pending follow-ups for an already-sent
|
|
374
|
+
campaign while retaining its sent history. Permanent received-email deletion
|
|
375
|
+
acknowledges a durable cleanup request; attachment/object cleanup can finish
|
|
376
|
+
asynchronously. Retrying that deletion is safe; it cannot be undone after the
|
|
377
|
+
purge request is accepted.
|
package/bin/senddart.js
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
const { main } = require('../src/cli');
|
|
5
|
+
|
|
6
|
+
main(process.argv.slice(2)).then(
|
|
7
|
+
(code) => {
|
|
8
|
+
process.exitCode = code;
|
|
9
|
+
},
|
|
10
|
+
(err) => {
|
|
11
|
+
process.stderr.write(`${err && err.message ? err.message : err}\n`);
|
|
12
|
+
process.exitCode = 1;
|
|
13
|
+
},
|
|
14
|
+
);
|
package/package.json
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "senddart-cli",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Official command-line interface for the SendDart email API.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"senddart",
|
|
7
|
+
"email",
|
|
8
|
+
"cli",
|
|
9
|
+
"api",
|
|
10
|
+
"transactional"
|
|
11
|
+
],
|
|
12
|
+
"license": "MIT",
|
|
13
|
+
"author": "SendDart",
|
|
14
|
+
"homepage": "https://www.senddart.com",
|
|
15
|
+
"repository": {
|
|
16
|
+
"type": "git",
|
|
17
|
+
"url": "git+https://github.com/shekhu10/senddart-sdks.git",
|
|
18
|
+
"directory": "senddart-cli"
|
|
19
|
+
},
|
|
20
|
+
"bugs": {
|
|
21
|
+
"url": "https://github.com/shekhu10/senddart-sdks/issues"
|
|
22
|
+
},
|
|
23
|
+
"bin": {
|
|
24
|
+
"senddart": "bin/senddart.js"
|
|
25
|
+
},
|
|
26
|
+
"main": "src/cli.js",
|
|
27
|
+
"files": [
|
|
28
|
+
"bin",
|
|
29
|
+
"src",
|
|
30
|
+
"README.md",
|
|
31
|
+
"LICENSE"
|
|
32
|
+
],
|
|
33
|
+
"scripts": {
|
|
34
|
+
"test": "node --test \"test/**/*.test.js\""
|
|
35
|
+
},
|
|
36
|
+
"engines": {
|
|
37
|
+
"node": ">=18"
|
|
38
|
+
},
|
|
39
|
+
"dependencies": {
|
|
40
|
+
"commander": "^12.1.0",
|
|
41
|
+
"senddart": "^1.0.0"
|
|
42
|
+
}
|
|
43
|
+
}
|
package/src/cli.js
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { Command } = require('commander');
|
|
4
|
+
const { CliError } = require('./helpers');
|
|
5
|
+
|
|
6
|
+
const VERSION = require('../package.json').version;
|
|
7
|
+
|
|
8
|
+
const RESOURCES = [
|
|
9
|
+
require('./commands/emails'),
|
|
10
|
+
require('./commands/domains'),
|
|
11
|
+
require('./commands/contacts'),
|
|
12
|
+
require('./commands/contact_properties'),
|
|
13
|
+
require('./commands/audiences'),
|
|
14
|
+
require('./commands/segments'),
|
|
15
|
+
require('./commands/topics'),
|
|
16
|
+
require('./commands/campaigns'),
|
|
17
|
+
require('./commands/templates'),
|
|
18
|
+
require('./commands/automations'),
|
|
19
|
+
require('./commands/webhooks'),
|
|
20
|
+
require('./commands/apikeys'),
|
|
21
|
+
require('./commands/events'),
|
|
22
|
+
require('./commands/logs'),
|
|
23
|
+
require('./commands/polls'),
|
|
24
|
+
];
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Build the execution context. Everything side-effectful (client construction,
|
|
28
|
+
* writing, environment) is injectable so tests can run the command layer with
|
|
29
|
+
* a mocked SDK client.
|
|
30
|
+
*/
|
|
31
|
+
function createContext(overrides = {}) {
|
|
32
|
+
return {
|
|
33
|
+
createClient(apiKey, options) {
|
|
34
|
+
const { SendDart } = require('senddart');
|
|
35
|
+
return new SendDart(apiKey, options);
|
|
36
|
+
},
|
|
37
|
+
// Pure, offline signature check. The SDK exports it as a standalone
|
|
38
|
+
// function precisely so it can be used WITHOUT a client — `webhooks verify`
|
|
39
|
+
// makes no HTTP request, so it must not demand an API key it never sends.
|
|
40
|
+
verifyWebhook(payload, headers, secret, options) {
|
|
41
|
+
const { verifyWebhookSignature } = require('senddart');
|
|
42
|
+
return verifyWebhookSignature(payload, headers, secret, options);
|
|
43
|
+
},
|
|
44
|
+
stdout: (s) => process.stdout.write(s),
|
|
45
|
+
stderr: (s) => process.stderr.write(s),
|
|
46
|
+
env: process.env,
|
|
47
|
+
exitCode: 0,
|
|
48
|
+
...overrides,
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Resolve auth/base-url flags (falling back to env) into an SDK client. */
|
|
53
|
+
function getClient(ctx, opts) {
|
|
54
|
+
const apiKey = opts.apiKey || ctx.env.SENDDART_API_KEY;
|
|
55
|
+
if (!apiKey) {
|
|
56
|
+
throw new CliError('Missing API key. Set the SENDDART_API_KEY environment variable or pass --api-key.');
|
|
57
|
+
}
|
|
58
|
+
const baseUrl = opts.baseUrl || ctx.env.SENDDART_BASE_URL;
|
|
59
|
+
return ctx.createClient(apiKey, baseUrl ? { baseUrl } : {});
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Print a success payload: pretty JSON by default, raw compact with --json. */
|
|
63
|
+
function print(ctx, data, opts) {
|
|
64
|
+
const s = opts.json ? JSON.stringify(data) : JSON.stringify(data, null, 2);
|
|
65
|
+
ctx.stdout(`${s}\n`);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Print an API/CLI error to stderr and mark the run failed. `--json` means
|
|
70
|
+
* "raw compact JSON output" for BOTH streams — an error printed pretty while
|
|
71
|
+
* the flag asked for compact made the flag a half-truth.
|
|
72
|
+
*/
|
|
73
|
+
function fail(ctx, error, opts = {}) {
|
|
74
|
+
ctx.stderr(`${opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2)}\n`);
|
|
75
|
+
ctx.exitCode = 1;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Build the toolkit passed to each resource module: `group` creates a
|
|
80
|
+
* top-level resource command, `leaf` a subcommand carrying the shared
|
|
81
|
+
* auth/output flags, and `act` wires a handler that receives the SDK client
|
|
82
|
+
* and returns its `{ data, error }` result.
|
|
83
|
+
*/
|
|
84
|
+
function makeToolkit(program, ctx) {
|
|
85
|
+
// Commands declared `local` make no HTTP request, so they neither resolve a
|
|
86
|
+
// client nor advertise the auth flags. Declared once, on the leaf; `act` reads
|
|
87
|
+
// it back rather than taking a second, drift-prone copy of the same fact.
|
|
88
|
+
const localCommands = new WeakSet();
|
|
89
|
+
|
|
90
|
+
function group(name, description) {
|
|
91
|
+
return program.command(name).description(description);
|
|
92
|
+
}
|
|
93
|
+
function leaf(parent, spec, description, options = {}) {
|
|
94
|
+
const cmd = parent.command(spec).description(description);
|
|
95
|
+
if (options.local) {
|
|
96
|
+
localCommands.add(cmd);
|
|
97
|
+
} else {
|
|
98
|
+
cmd
|
|
99
|
+
.option('--api-key <key>', 'API key (default: SENDDART_API_KEY env var)')
|
|
100
|
+
.option('--base-url <url>', 'API base URL (default: SENDDART_BASE_URL env var)');
|
|
101
|
+
}
|
|
102
|
+
// `--json` still applies: a local command prints its result like any other.
|
|
103
|
+
return cmd.option('--json', 'raw compact JSON output (default: pretty-printed)');
|
|
104
|
+
}
|
|
105
|
+
function act(cmd, handler) {
|
|
106
|
+
cmd.action(async (...cbArgs) => {
|
|
107
|
+
const command = cbArgs[cbArgs.length - 1];
|
|
108
|
+
const args = cbArgs.slice(0, -1);
|
|
109
|
+
const opts = command.opts();
|
|
110
|
+
try {
|
|
111
|
+
const client = localCommands.has(cmd) ? undefined : getClient(ctx, opts);
|
|
112
|
+
const result = await handler({ client, ctx, opts, args });
|
|
113
|
+
if (result && result.error) return fail(ctx, result.error, opts);
|
|
114
|
+
print(ctx, result ? result.data : null, opts);
|
|
115
|
+
// Some endpoints answer 200 while reporting a failed operation in the
|
|
116
|
+
// body (e.g. POST /webhooks/:id/test → { ok: false }). A handler flags
|
|
117
|
+
// that with `failed` so the body is still printed but the shell sees 1.
|
|
118
|
+
if (result && result.failed) ctx.exitCode = 1;
|
|
119
|
+
return undefined;
|
|
120
|
+
} catch (err) {
|
|
121
|
+
if (err instanceof CliError) {
|
|
122
|
+
return fail(ctx, { statusCode: null, name: 'cli_error', message: err.message }, opts);
|
|
123
|
+
}
|
|
124
|
+
throw err;
|
|
125
|
+
}
|
|
126
|
+
});
|
|
127
|
+
return cmd;
|
|
128
|
+
}
|
|
129
|
+
return { group, leaf, act };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** Assemble the full commander program for the given context. */
|
|
133
|
+
function buildProgram(ctx) {
|
|
134
|
+
const program = new Command();
|
|
135
|
+
program
|
|
136
|
+
.name('senddart')
|
|
137
|
+
.description('Official SendDart CLI — send email, manage domains, contacts, campaigns and more.')
|
|
138
|
+
.version(VERSION)
|
|
139
|
+
.exitOverride()
|
|
140
|
+
.configureOutput({
|
|
141
|
+
writeOut: (s) => ctx.stdout(s),
|
|
142
|
+
writeErr: (s) => ctx.stderr(s),
|
|
143
|
+
})
|
|
144
|
+
.addHelpText(
|
|
145
|
+
'after',
|
|
146
|
+
'\nAuthentication:\n Set SENDDART_API_KEY (or pass --api-key to any command).\n Set SENDDART_BASE_URL (or --base-url) to target a different API host.\n\nExamples:\n senddart emails send --from \'Acme <hi@yourdomain.com>\' --to delivered@test.senddart.com --subject hello --html \'<p>hi</p>\'\n senddart contacts list --domain yourdomain.com\n senddart events send --domain yourdomain.com --name signup.completed --email ada@example.com --data \'{"plan":"pro"}\'',
|
|
147
|
+
);
|
|
148
|
+
|
|
149
|
+
const toolkit = makeToolkit(program, ctx);
|
|
150
|
+
for (const resource of RESOURCES) resource.register(toolkit);
|
|
151
|
+
return program;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Parse and execute argv (user args only, no node/script prefix).
|
|
156
|
+
* Returns the exit code; never calls process.exit itself.
|
|
157
|
+
*/
|
|
158
|
+
async function run(ctx, argv) {
|
|
159
|
+
const program = buildProgram(ctx);
|
|
160
|
+
try {
|
|
161
|
+
await program.parseAsync(argv, { from: 'user' });
|
|
162
|
+
} catch (err) {
|
|
163
|
+
// Commander throws for --help/--version (exitCode 0) and usage errors
|
|
164
|
+
// (exitCode 1) because of exitOverride; the message is already printed.
|
|
165
|
+
if (err && typeof err.exitCode === 'number' && String(err.code || '').startsWith('commander.')) {
|
|
166
|
+
if (err.exitCode !== 0) ctx.exitCode = err.exitCode;
|
|
167
|
+
return ctx.exitCode;
|
|
168
|
+
}
|
|
169
|
+
throw err;
|
|
170
|
+
}
|
|
171
|
+
return ctx.exitCode;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/** Entry point used by bin/senddart.js. */
|
|
175
|
+
function main(argv) {
|
|
176
|
+
return run(createContext(), argv);
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
module.exports = { createContext, buildProgram, run, main };
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { withPagination, pagination } = require('../helpers');
|
|
4
|
+
|
|
5
|
+
// `list` is the whole group on purpose. Creating, re-scoping and revoking keys
|
|
6
|
+
// happens in the dashboard, behind a signed-in session — so a key that leaks
|
|
7
|
+
// cannot mint itself a replacement or widen its own access from the CLI.
|
|
8
|
+
function register({ group, leaf, act }) {
|
|
9
|
+
const apiKeys = group('api-keys', 'Inspect API keys (create/revoke live in the dashboard)');
|
|
10
|
+
|
|
11
|
+
act(withPagination(leaf(apiKeys, 'list', 'List API keys')), ({ client, opts }) =>
|
|
12
|
+
client.apiKeys.list(pagination(opts)),
|
|
13
|
+
);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
module.exports = { register };
|