senddart 1.0.0 → 1.1.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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 283eab8c1be47c578fa465596d35ff85abf8b3c504ef041d21a3fbb23631697f
4
- data.tar.gz: ae074cff46085c39c5d9b801c1324e5259a6e172f49ddd40bbb2516cea99fcd1
3
+ metadata.gz: 833e007427682688d38465386e95f32bac7e88f9d2f2fbd9e29ce7d10039c8eb
4
+ data.tar.gz: 1ae32aeab81cb788eb4329694f4f725bc2353fc4f5d188091111ef83a415f5a2
5
5
  SHA512:
6
- metadata.gz: 4b4ab1becf2e4a760d96883384adf46743c3e8e19346f35858c0edc5cc46a7690635c538651bb932d0ee5d192a5224ef019e561a8154376b710b1d65dbe9da55
7
- data.tar.gz: d5db56168fcad952b541148cf9c944463e6092735f267189ab860383ea0f6abe5a13eeded4ecfbd47d7e62ac685923c4f985aa23ce9b933418d614569577a795
6
+ metadata.gz: '0583152e4d5fe78de661c8e317d5a4eff5eb26598c775e7a06c6e43296579c957f67c98f6a2d3b6fc04fdb842706f6e8c8f3a810db770fb98e08adcebeb1ed4a'
7
+ data.tar.gz: d6e76bcd6df3a6306137061cc8687dcc07ce1d79a9710828f1f768d12a41a7537c93d2bec688d1c9c286421cb6d61f77d490020df7207e82897279caf017df2f
data/README.md CHANGED
@@ -56,7 +56,7 @@ rescue SendDart::Error => e
56
56
  end
57
57
  ```
58
58
 
59
- Branch on `e.name`, never on `e.message` — messages are sanitized server-side and may change. The same `name` can arrive with different HTTP statuses depending on the endpoint, so read `e.status_code` rather than assuming one. Common names: `missing_api_key` (401), `restricted_api_key` (401, the key lacks the scope), `invalid_api_key` (403), `validation_error` (422), `not_found` (404), `plan_limit_reached` (402), `daily_quota_exceeded` / `monthly_quota_exceeded` / `rate_limit_exceeded` (429).
59
+ Branch on `e.name`, never on `e.message` — messages are sanitized server-side and may change. The same `name` can arrive with different HTTP statuses depending on the endpoint, so read `e.status_code` rather than assuming one. Common names: `missing_api_key` (401), `restricted_api_key` (401, the key lacks the scope — e.g. a sending-only key calling `ApiKeys.create`), `invalid_api_key` (403), `validation_error` (422), `not_found` (404), `plan_limit_reached` (402), `daily_quota_exceeded` / `monthly_quota_exceeded` / `rate_limit_exceeded` (429).
60
60
 
61
61
  Some errors carry more than that envelope. The extras are readers on the error and are `nil` on an ordinary one:
62
62
 
@@ -82,7 +82,7 @@ rescue SendDart::Error => e
82
82
  end
83
83
  ```
84
84
 
85
- `e.body` is the whole parsed error body, so a field newer than this SDK version is still reachable.
85
+ `e.body` is the whole parsed error body, so a field newer than this SDK version is still reachable. `e.waiting` / `e.oldest` carry the extras of a 409 `waiting_enrollments` (see Automations), and `e.response` / `e.headers` / `e.rate_limit` the failed response's headers (see [Response headers](#response-headers)).
86
86
 
87
87
  Every request carries a `User-Agent` automatically — the API rejects requests without one with a 403 `validation_error`.
88
88
 
@@ -105,7 +105,15 @@ SendDart::Emails.send({ from: from, to: to, subject: subject, html: html })
105
105
  SendDart::Emails.list({ limit: 20, after: cursor }) # cursor pagination
106
106
  SendDart::Emails.list({ status: "bounced", search: "acme.com" }) # filters
107
107
  SendDart::Emails.list({ folder: "scheduled" }) # one of outbox | sent | scheduled | failed — any other value is rejected (422)
108
+ SendDart::Emails.list({ engagement: "opened" }) # delivered | opened | clicked | replied | bounced | complained
109
+ SendDart::Emails.list({ campaign_scope: "direct" }) # one-off sends only, no campaign mail
110
+ # Created between two ISO 8601 instants (after < before; a malformed value is a 422).
111
+ # `created_*`, because `after` / `before` are the pagination cursors.
112
+ SendDart::Emails.list({ created_after: "2026-01-01T00:00:00Z", created_before: "2026-01-31T00:00:00Z" })
113
+ SendDart::Emails.list({ statuses: %w[bounced failed], api_key_id: "41", query: "acme" }) # several statuses; the sending key
108
114
  SendDart::Emails.sources # per-campaign/automation send metrics
115
+ SendDart::Emails.metrics({ start_date: "2026-11-01", end_date: "2026-11-21", dimensions: %w[period domain] })
116
+ SendDart::Emails.share(email_id) # public read-only link, valid 48 h
109
117
  SendDart::Emails.get(email_id)
110
118
  SendDart::Emails.list_attachments(email_id)
111
119
  SendDart::Emails.get_attachment(email_id, attachment_id)
@@ -133,8 +141,10 @@ SendDart::Emails.send({
133
141
 
134
142
  ```ruby
135
143
  SendDart::Emails::Receiving.list
144
+ SendDart::Emails::Receiving.list({ query: "invoice", created_after: "2026-11-01T00:00:00Z" })
136
145
  SendDart::Emails::Receiving.list_addresses # per-address inbound stats
137
146
  SendDart::Emails::Receiving.get(id)
147
+ SendDart::Emails::Receiving.update(id, { read: true }) # mark read / unread; returns the email with "read" and "read_at"
138
148
  SendDart::Emails::Receiving.list_attachments(id)
139
149
  SendDart::Emails::Receiving.get_attachment(id, attachment_id) # => raw bytes (String)
140
150
  SendDart::Emails::Receiving.get_raw(id) # => original RFC822 message
@@ -159,14 +169,10 @@ SendDart::Domains.delete(id)
159
169
  SendDart::Domains.claim({ name: "yourdomain.com" })
160
170
  SendDart::Domains.get_claim(id)
161
171
  SendDart::Domains.verify_claim(id)
162
-
163
- # One-click DNS setup
164
- SendDart::Domains.detect_dns(id)
165
- SendDart::Domains.apply_cloudflare_dns(id, { token: cf_token })
166
- SendDart::Domains.apply_godaddy_dns(id, { key: key, secret: secret })
167
- SendDart::Domains.apply_namecheap_dns(id, { apiUser: user, apiKey: key })
168
172
  ```
169
173
 
174
+ **Deprecated:** `detect_dns`, `apply_cloudflare_dns`, `apply_godaddy_dns` and `apply_namecheap_dns`. Automatic DNS setup was retired on 2026-10-15 and the API now answers `410 dns_setup_disabled` to all four. They still send their request (so existing code keeps running and gets that 410 as a `SendDart::Error`), print a `[DEPRECATION]` warning on `$stderr` (silenced by `ruby -W0`), and will be removed in 2.0. Add the records from `Domains.get` / `Domains.records_csv` at your DNS provider instead.
175
+
170
176
  ## Contacts (domain-first)
171
177
 
172
178
  ```ruby
@@ -189,8 +195,16 @@ SendDart::Contacts.import({ audience_id: aud_id, csv: "email,company\na@b.com,Ac
189
195
 
190
196
  # CSV too big to inline (5 MB / 10,000 rows)? Upload it directly, then import by key.
191
197
  slot = SendDart::Contacts.create_import_upload({ audience_id: aud_id, filename: "list.csv", size: bytes })
192
- # PUT the file to slot["upload_url"], then:
198
+ # PUT the file to slot["upload_url"], then optionally dry-run it (nothing is written) …
199
+ preview = SendDart::Contacts.preview_import({ audience_id: aud_id, storage_key: slot["storage_key"] })
200
+ preview["valid_rows"]; preview["new_contacts"]; preview["warnings"]; preview["sample"] # up to 20 parsed rows
201
+ # … and import it:
193
202
  SendDart::Contacts.import({ audience_id: aud_id, storage_key: slot["storage_key"] })
203
+ # Map columns yourself (one column must be email): preview and import both take `mapping`;
204
+ # the preview answers "header_row", "header_is_data" and the "mapping" it used.
205
+ mapping = { "E-mail" => "email", "Given name" => "first_name", "Notes" => "ignore", "Company" => "company" }
206
+ SendDart::Contacts.preview_import({ audience_id: aud_id, storage_key: slot["storage_key"], mapping: mapping })
207
+ SendDart::Contacts.import({ audience_id: aud_id, storage_key: slot["storage_key"], mapping: mapping })
194
208
 
195
209
  # Segments & topics per contact
196
210
  SendDart::Contacts.add_to_segment(contact_id, segment_id)
@@ -226,6 +240,10 @@ SendDart::Segments.contacts(id) # preview who matches
226
240
  SendDart::Segments.update(id, { name: "VIP customers" })
227
241
  SendDart::Segments.delete(id)
228
242
 
243
+ # Move contacts to another segment: one (contact_id:) or all (all: true).
244
+ check = SendDart::Segments.move(id, { destination_id: other_id, all: true, preview: true }) # counts only
245
+ SendDart::Segments.move(id, { destination_id: other_id, all: true, expected_count: check["count"] }) # 409 if it changed
246
+
229
247
  SendDart::Topics.create({ domain: "yourdomain.com", name: "Product updates", default_subscription: "opt_in" })
230
248
  SendDart::Topics.list({ domain: "yourdomain.com" })
231
249
  SendDart::Topics.update(id, { description: "New features" })
@@ -248,11 +266,40 @@ SendDart::Campaigns.send(campaign["id"], { scheduled_at: "2026-08-01T09:00:00Z"
248
266
  SendDart::Campaigns.cancel(campaign["id"])
249
267
  SendDart::Campaigns.stats(campaign["id"])
250
268
  SendDart::Campaigns.engagement(campaign["id"]) # who opened / clicked / replied
269
+ SendDart::Campaigns.recipients(campaign["id"], { type: "clicked", limit: 50 }) # page with after: <last id>
270
+ SendDart::Campaigns.clicked_links(campaign["id"], { limit: 10 }) # most-clicked first
251
271
  SendDart::Campaigns.ab(campaign["id"]) # A/B winner evaluation
252
272
  SendDart::Campaigns.get(campaign["id"])
253
273
  SendDart::Campaigns.list({ limit: 25 })
254
- SendDart::Campaigns.update(campaign["id"], { subject: "Bigger news" })
274
+ SendDart::Campaigns.update(campaign["id"], { subject: "Bigger news" }) # draft only
275
+ SendDart::Campaigns.update(campaign["id"], { name: "Spring launch" }) # a name-only rename works in any status
255
276
  SendDart::Campaigns.delete(campaign["id"])
277
+
278
+ # Check it in a real inbox first: 1-5 addresses, subject prefixed "[Test] ", status unchanged.
279
+ SendDart::Campaigns.test(campaign["id"], { to: ["you@yourdomain.com"] }, { idempotency_key: "test-1" })
280
+
281
+ SendDart::Campaigns.duplicate(campaign["id"]) # new draft copy => { "object" => "campaign", "id", "name" }
282
+ SendDart::Campaigns.save_as_template(campaign["id"]) # new draft template => { "object" => "template", "id", "name" }
283
+ SendDart::Campaigns.continue_sending(campaign["id"]) # resume a `paused` campaign => { "status" => "queued", "remaining" }
284
+ SendDart::Campaigns.batches(campaign["id"]) # batch history (not a paginated list)
285
+
286
+ # Clean bounced recipients out of the audience.
287
+ bounced = SendDart::Campaigns.bounced_contacts(campaign["id"]) # { "count", "sample", "version" }
288
+ SendDart::Campaigns.remove_bounced_contacts(campaign["id"], { version: bounced["version"] }) # 409 if the list changed
289
+
290
+ # Follow-ups on a sending/sent campaign (at most 5 active).
291
+ fu = SendDart::Campaigns.create_followup(campaign["id"], {
292
+ condition: "opened", # delivered | opened | clicked | replied
293
+ delay_days: 2, delay_hours: 0,
294
+ html: "<p>Did you see this?</p>",
295
+ subject: "" # empty or omitted = reuse the campaign subject
296
+ })
297
+ SendDart::Campaigns.get_followup(campaign["id"], fu["id"])["delivery_counts"]
298
+ # update_followup takes the FULL create params again, plus resend_previously_sent:
299
+ SendDart::Campaigns.update_followup(campaign["id"], fu["id"], {
300
+ condition: "opened", delay_days: 3, delay_hours: 0, html: "<p>Last call</p>", resend_previously_sent: false
301
+ })
302
+ SendDart::Campaigns.delete_followup(campaign["id"], fu["id"]) # cancels it => { "canceled" => true }
256
303
  ```
257
304
 
258
305
  ## Templates
@@ -261,7 +308,8 @@ SendDart::Campaigns.delete(campaign["id"])
261
308
  tmpl = SendDart::Templates.create({ name: "Welcome", subject: "Welcome!", html: "<p>Hi {{first_name}}</p>" })
262
309
  SendDart::Templates.publish(tmpl["id"])
263
310
  SendDart::Templates.duplicate(tmpl["id"], { name: "Welcome v2" })
264
- SendDart::Templates.get(tmpl["id"])
311
+ SendDart::Templates.get(tmpl["id"]) # carries "folder_id" and "created_by"
312
+ SendDart::Templates.list({ folder_id: "root" }) # or a folder id
265
313
  SendDart::Templates.list
266
314
  SendDart::Templates.update(tmpl["id"], { subject: "Welcome aboard!" })
267
315
  SendDart::Templates.delete(tmpl["id"])
@@ -286,6 +334,7 @@ SendDart::Automations.add_step(automation["id"], { type: "send_email", config: {
286
334
  # add_step, ignored here — so delete and re-add a step to re-key it.
287
335
  SendDart::Automations.update_step(automation["id"], step_id, { type: "send_email", config: { template_id: tmpl_id, subject: "New subject" } })
288
336
  SendDart::Automations.update(automation["id"], { status: "enabled" })
337
+ SendDart::Automations.duplicate(automation["id"]) # a full copy, starting `disabled`
289
338
 
290
339
  # Or describe the flow and let the server build the steps (automation must be stopped)
291
340
  SendDart::Automations.create_with_ai(automation["id"], { prompt: "Wait 2 days, then send the onboarding email" })
@@ -302,17 +351,36 @@ SendDart::Events.send({
302
351
  # Event names cannot start with the reserved "senddart:" prefix.
303
352
  SendDart::Events.create({ name: "signup.completed", schema: { plan: "string" } })
304
353
  SendDart::Events.list
354
+ SendDart::Events.get("signup.completed") # by id or by name
305
355
  SendDart::Events.update(event_id, { schema: { plan: "string", seats: "number" } }) # name is immutable
306
356
  SendDart::Events.delete(event_id)
307
357
 
308
358
  # Inspect execution
309
- runs = SendDart::Automations.runs(automation["id"], { limit: 25, status: ["failed"] })
359
+ runs = SendDart::Automations.runs(automation["id"], { limit: 25, status: %w[running failed],
360
+ created_after: "2026-11-01T00:00:00Z" })
310
361
  SendDart::Automations.get_run(automation["id"], runs["data"].first["id"])
362
+ SendDart::Automations.cancel_run(automation["id"], runs["data"].first["id"])
311
363
  SendDart::Automations.delete_step(automation["id"], step_id)
312
364
  SendDart::Automations.stop(automation["id"])
313
365
  SendDart::Automations.delete(automation["id"])
314
366
  ```
315
367
 
368
+ `Automations.list` rows also carry `"runs"` (the automation's run count), and `"status"` may read `"draining"` while an automation being switched off finishes its in-flight runs.
369
+
370
+ Re-enabling an automation whose contacts have been waiting more than an hour answers **409 `waiting_enrollments`** (never retried automatically). The error says how many are waiting and since when; repeat the call with `on_waiting:` to choose what happens to them:
371
+
372
+ ```ruby
373
+ begin
374
+ SendDart::Automations.update(id, { status: "enabled" })
375
+ rescue SendDart::Error => e
376
+ raise unless e.name == "waiting_enrollments"
377
+
378
+ puts "#{e.waiting} contacts waiting since #{e.oldest}" # oldest may be nil
379
+ # "resume" runs their next step now; "skip_waiting" skips them and enables for new contacts only.
380
+ SendDart::Automations.update(id, { status: "enabled", on_waiting: "resume" })
381
+ end
382
+ ```
383
+
316
384
  ## Webhooks
317
385
 
318
386
  ```ruby
@@ -327,9 +395,16 @@ SendDart::Webhooks.update(hook["id"], { status: "disabled" })
327
395
  SendDart::Webhooks.rotate(hook["id"]) # new secret returned once
328
396
  SendDart::Webhooks.test(hook["id"])
329
397
  SendDart::Webhooks.delete(hook["id"])
398
+
399
+ # What the endpoint was sent, and redelivery
400
+ events = SendDart::Webhooks.list_events(hook["id"], { status: "failed", type: "email.bounced" })
401
+ event_id = events["data"].first["id"]
402
+ SendDart::Webhooks.get_event(hook["id"], event_id) # with "payload"
403
+ SendDart::Webhooks.list_event_attempts(hook["id"], event_id)
404
+ SendDart::Webhooks.replay_event(hook["id"], event_id) # one attempt, now
330
405
  ```
331
406
 
332
- Endpoints must be `https://` and must not resolve to a private address. Valid event names are `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.failed`, `email.scheduled`, `email.suppressed`, `email.received`, `email.replied`, `email.unsubscribed`, `contact.created`, `contact.updated`, `contact.deleted`, `domain.created`, `domain.updated` and `domain.deleted`. Anything else is a 422.
407
+ Endpoints must be `https://` and must not resolve to a private address. Valid event names are `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.failed`, `email.scheduled`, `email.suppressed`, `email.received`, `email.replied`, `email.unsubscribed`, `contact.created`, `contact.updated`, `contact.deleted`, `contact.topics.updated`, `domain.created`, `domain.updated`, `domain.deleted`, `suppression.added`, `suppression.removed`, `topic.created`, `topic.updated`, `topic.deleted`, `inbox.created`, `inbox.updated`, `inbox.deleted`, `inbox.email.received`, `inbox.email.sent`, `inbox.thread.created`, `inbox.thread.assigned`, `inbox.thread.unassigned`, `inbox.thread.folder.updated`, `inbox.thread.labels.updated`, `inbox.draft.created`, `inbox.draft.updated`, `inbox.draft.deleted` and `inbox.draft.sent`. Anything else is a 422.
333
408
 
334
409
  `Webhooks.test` returns HTTP 200 even when the delivery failed — it does not raise. The outcome is `result["ok"]`, with `result["status"]` (your endpoint's HTTP status, when it responded) and `result["error"]` (e.g. `"lookup_failed"`):
335
410
 
@@ -359,10 +434,65 @@ head :unauthorized unless result[:valid]
359
434
 
360
435
  Pass `tolerance: 0` to skip the timestamp freshness check (default 300 seconds).
361
436
 
362
- ## API keys, Logs & Polls
437
+ ## Inboxes
438
+
439
+ Shared inboxes: conversations (threads), their emails, labels, drafts and the AI agent settings. Path ids come first, in path order, then one params hash.
363
440
 
364
441
  ```ruby
365
- SendDart::ApiKeys.list # `token` is the 8-character display prefix, never the secret
442
+ inbox = SendDart::Inboxes.create({ email_address: "support@yourdomain.com", name: "Support" })
443
+ SendDart::Inboxes.list
444
+ SendDart::Inboxes.update(inbox["id"], { from_name: "Acme Support" })
445
+
446
+ label = SendDart::Inboxes::Labels.create(inbox["id"], { name: "Billing", color: "amber" })
447
+ SendDart::Inboxes::Labels.list(inbox["id"])
448
+
449
+ threads = SendDart::Inboxes::Threads.list(inbox["id"], { folder: "inbox", unread: true })
450
+ SendDart::Inboxes::Threads.search(inbox["id"], { query: "refund", from: "ada@example.com" })
451
+ thread_id = threads["data"].first["id"]
452
+ SendDart::Inboxes::Threads.update(inbox["id"], thread_id, { read: true, assignee: "me@yourdomain.com" })
453
+ SendDart::Inboxes::Threads.add_labels(inbox["id"], thread_id, { labels: [label["id"]] })
454
+ SendDart::Inboxes::Threads.set_labels(inbox["id"], thread_id, { labels: [] }) # clear
455
+ emails = SendDart::Inboxes::Threads.list_emails(inbox["id"], thread_id)
456
+ email_id = emails["data"].last["id"]
457
+ SendDart::Inboxes::Threads.reply(inbox["id"], thread_id, email_id, { html: "<p>Done!</p>" },
458
+ { idempotency_key: "reply-1" })
459
+ SendDart::Inboxes::Threads.forward(inbox["id"], thread_id, email_id, { to: "billing@yourdomain.com" })
460
+
461
+ draft = SendDart::Inboxes::Drafts.create(inbox["id"], { mode: "reply", email_id: email_id, html: "<p>Hi</p>" })
462
+ SendDart::Inboxes::Drafts.update(inbox["id"], draft["id"], { subject: "Re: your order" })
463
+ SendDart::Inboxes::Drafts.send(inbox["id"], draft["id"])
464
+
465
+ SendDart::Inboxes::Agent.get(inbox["id"])
466
+ SendDart::Inboxes::Agent.update(inbox["id"], { instructions: "Be brief.", tone: { length: 30 } })
467
+ ```
468
+
469
+ Replying, forwarding and sending a draft need a full-access key and honour `idempotency_key`. Inbox refusals carry a machine `"code"` in `e.body` (e.g. `"receiving_choice_required"`).
470
+
471
+ ## Suppressions & usage
472
+
473
+ ```ruby
474
+ SendDart::Suppressions.create({ email: "someone@example.com" })
475
+ SendDart::Suppressions.list({ origin: "bounce", search: "example.com" })
476
+ SendDart::Suppressions.get("someone@example.com") # by id or address
477
+ SendDart::Suppressions.delete("someone@example.com")
478
+ SendDart::Suppressions.batch_add({ emails: ["a@example.com", "b@example.com"] }) # => "data" + "skipped"
479
+ SendDart::Suppressions.batch_remove({ ids: ["12"], emails: ["b@example.com"] })
480
+
481
+ SendDart::Usage.get # meters and limits; a "limit" of nil means unlimited
482
+ ```
483
+
484
+ ## Account, API keys, Logs & Polls
485
+
486
+ ```ruby
487
+ SendDart::Account.get # => { "id", "email", "plan" (effective), "stored_plan", "plan_expires_at",
488
+ # "account_status", "timezone_name", "timezone_offset", "created_at" }
489
+
490
+ SendDart::ApiKeys.list # `token` is the 8-character display prefix, never the secret;
491
+ # rows also carry "total_uses" and "created_by" (email or nil)
492
+ key = SendDart::ApiKeys.create({ name: "Production", permission: "sending_access", domain_ids: [domain_id] })
493
+ key["token"] # the secret, shown once
494
+ SendDart::ApiKeys.update(key["id"], { name: "Production (EU)" })
495
+ SendDart::ApiKeys.delete(key["id"])
366
496
 
367
497
  SendDart::Logs.list({ limit: 100, method: "POST", status: 429 })
368
498
  SendDart::Logs.get(log_id)
@@ -371,14 +501,11 @@ SendDart::Polls.list
371
501
  SendDart::Polls.get(email_id) # aggregated answer breakdown
372
502
  ```
373
503
 
374
- `SendDart::ApiKeys.list` is the whole API-key surface: the SDK deliberately
375
- exposes no method to create, re-scope or revoke a key. Key lifecycle belongs to
376
- a signed-in dashboard session, and the API enforces it — `POST /api-keys`,
377
- `PATCH /api-keys/:id` and `DELETE /api-keys/:id` answer `403 dashboard_only` to
378
- any API-key caller, whatever its permission. That is the point: a key that leaks
379
- cannot mint itself a replacement, widen its own access, or revoke the keys you
380
- would use to shut it off. Create and revoke keys at
381
- [senddart.com](https://www.senddart.com).
504
+ `ApiKeys.create`, `ApiKeys.update` and `ApiKeys.delete` work with a
505
+ **full-access** key (or in the dashboard). A sending-only key is refused with
506
+ `401 restricted_api_key`, so a leaked sending key cannot mint itself a
507
+ full-access one. A domain restriction (`domain_id` / `domain_ids`) is only valid
508
+ on a `sending_access` key.
382
509
 
383
510
  ## Pagination
384
511
 
@@ -393,6 +520,20 @@ page["data"] # => [...]
393
520
 
394
521
  `limit` is an integer between 1 and 100 (default 20); `after` and `before` are item ids and cannot be combined. An unknown cursor returns an empty page, not an error. There is no `total` and no `next_cursor` — page forward with the last `data` entry's `id` as `after`.
395
522
 
523
+ To read every row without writing that loop, `SendDart.paginate` returns a lazy `Enumerator` over the items. It requests the next page only when it gets there, so `.first(n)` stops early:
524
+
525
+ ```ruby
526
+ SendDart.paginate(SendDart::Campaigns.method(:list), { limit: 100 }).each do |campaign|
527
+ puts campaign["id"]
528
+ end
529
+
530
+ # Lists that take an id first: pass a block that fetches one page.
531
+ emails = SendDart.paginate({ limit: 100 }) { |page| SendDart::Segments.contacts(segment_id, page) }
532
+ .map { |c| c["email"] }
533
+ ```
534
+
535
+ It pages forward with `after` (an `after` you pass is the starting cursor) until `has_more` is `false`. `before` is rejected with an `ArgumentError`. Pass `limit` so each request reads a full page.
536
+
396
537
  Defaults differ per endpoint. `GET /templates`, `/webhooks`, `/audiences`, `/automations`, `/events` and `/automations/:id/runs` cap an unpaginated call at 20 rows. `/domains`, `/api-keys`, `/topics`, `/campaigns`, `/contacts`, `/contact-properties`, `/segments` and `/polls` instead return the collection in one response when you pass neither `limit` nor a cursor — but still bounded, at 1,000 rows. That ceiling is not silent: `has_more` is `true` when it bites, so keep paging with `after` rather than treating the first response as the whole table. Always pass `limit` if you depend on page size.
397
538
 
398
539
  ## Idempotency
@@ -414,6 +555,31 @@ Reusing a key replays the original response; reusing it with a *different* body
414
555
 
415
556
  Only the `/emails` **send** routes are rate-limited: **30 requests per minute per IP**. Reads (`GET /emails`, `GET /emails/:id`, the `receiving` subtree and attachment listings) are NOT subject to that cap, so paging a large list no longer risks a 429. Capped responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers (on successes too) so you can throttle before being rejected. The SDK retries a 429 or 503 automatically — up to `SendDart.max_retries` times (default 2), honouring `Retry-After`.
416
557
 
558
+ ## Response headers
559
+
560
+ Methods keep returning the parsed body. The status and headers of the most recent response are on `SendDart.last_response`, a `SendDart::Response`. It is kept **per thread** (and per fiber), so concurrent threads never read each other's; read it right after the call you care about. A raised `SendDart::Error` carries its own copy as `e.response`.
561
+
562
+ ```ruby
563
+ SendDart::Emails.send(params)
564
+ res = SendDart.last_response
565
+ res.status_code # => 200
566
+ res["RateLimit-Remaining"] # => "29" (case-insensitive)
567
+ res.headers # => { "ratelimit-remaining" => "29", ... } (lower-cased keys)
568
+
569
+ rl = res.rate_limit # SendDart::RateLimit; each field nil when the header is absent
570
+ rl.limit; rl.remaining # => 30, 29 RateLimit-Limit / RateLimit-Remaining
571
+ rl.reset # => 41 RateLimit-Reset (seconds until the window resets)
572
+ rl.retry_after # => nil Retry-After in seconds (an HTTP-date is converted)
573
+
574
+ begin
575
+ SendDart::Emails.send(params)
576
+ rescue SendDart::Error => e
577
+ sleep(e.rate_limit.retry_after || 1) if e.status_code == 429 # after the built-in retries ran out
578
+ end
579
+ ```
580
+
581
+ `last_response` and `e.response` describe the final attempt when the SDK retried. A call that gets no response at all (`missing_api_key`, or a network error) leaves `last_response` `nil`, and a `missing_api_key` error has `e.response == nil`.
582
+
417
583
  ## Documentation
418
584
 
419
585
  Full docs: <https://www.senddart.com/docs>
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+
3
+ module SendDart
4
+ # The account that owns the API key.
5
+ module Account
6
+ class << self
7
+ # GET /user (read scope) — { "id" => Integer, "email", "plan" (the
8
+ # effective plan, so a lapsed paid plan reads as its fallback),
9
+ # "stored_plan", "plan_expires_at" (String|nil), "account_status"
10
+ # ("active" | "suspended" | "closed"), "timezone_name" (String|nil),
11
+ # "timezone_offset" (Integer|nil), "created_at" }.
12
+ # SendDart::Account.get["plan"] # => "pro"
13
+ def get
14
+ Client.request(:get, "/user")
15
+ end
16
+ end
17
+ end
18
+ end
@@ -1,19 +1,42 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module SendDart
4
- # Listing only, by design. Keys are created, re-scoped and revoked in the
5
- # SendDart dashboard by a signed-in user — POST /api-keys,
6
- # PATCH /api-keys/:id and DELETE /api-keys/:id answer 403 `dashboard_only`
7
- # to every API-key caller, whatever its permission. Exposing only `list`
8
- # means a leaked key cannot mint itself a replacement or widen its access.
4
+ # API keys. Creating, updating and revoking a key needs a FULL-ACCESS key
5
+ # (or a signed-in dashboard session): a sending-only key is refused with
6
+ # 401 `restricted_api_key`, so a leaked sending key cannot mint itself a
7
+ # full-access one.
9
8
  module ApiKeys
10
9
  class << self
10
+ # Create a key. POST /api-keys — params: { name: (required, at most 50
11
+ # characters), permission: ("full_access" default | "sending_access"),
12
+ # domain_id: / domain_ids: (a restriction, sending_access keys only) }.
13
+ # Returns { "id", "object" => "api_key", "token" (the secret, shown
14
+ # ONCE), "domain_id", "domain_ids" }.
15
+ def create(params)
16
+ Client.request(:post, "/api-keys", body: params)
17
+ end
18
+
11
19
  # GET /api-keys — with no pagination params one page carries up to 1,000
12
20
  # non-revoked keys and `has_more` reports any truncation. `token` here is
13
- # the 8-character display prefix, never the secret.
21
+ # the 8-character display prefix, never the secret. Each row also
22
+ # carries "total_uses" (requests it has authenticated) and "created_by"
23
+ # (the creator's email, or nil when not recorded).
14
24
  def list(params = {})
15
25
  Client.request(:get, "/api-keys", query: Client.pagination(params))
16
26
  end
27
+
28
+ # Change name:, permission: (switching to full_access clears a domain
29
+ # restriction) or domain_id: / domain_ids:. The secret never changes.
30
+ # Returns the "api_key" row. PATCH /api-keys/:id
31
+ def update(key_id, params)
32
+ Client.request(:patch, "/api-keys/#{Client.path_escape(key_id)}", body: params)
33
+ end
34
+
35
+ # Revoke a key. Returns { "object" => "api_key", "id", "deleted" => true }.
36
+ # DELETE /api-keys/:id
37
+ def delete(key_id)
38
+ Client.request(:delete, "/api-keys/#{Client.path_escape(key_id)}")
39
+ end
17
40
  end
18
41
  end
19
42
  end
@@ -22,7 +22,9 @@ module SendDart
22
22
  Client.request(:get, "/automations/#{Client.path_escape(automation_id)}")
23
23
  end
24
24
 
25
- # GET /automations
25
+ # GET /automations — list rows also carry "runs" (the automation's run
26
+ # count); a single get does not. "status" may also read "draining"
27
+ # (being switched off while in-flight runs finish).
26
28
  def list(params = {})
27
29
  Client.request(:get, "/automations", query: Client.pagination(params))
28
30
  end
@@ -30,6 +32,13 @@ module SendDart
30
32
  # PATCH /automations/:id — params: { name:, status: "enabled"|"disabled", ... }
31
33
  # `trigger_config` ({ at:, timezone: }) updates the "senddart:schedule"
32
34
  # trigger's schedule (only valid on automations with that trigger).
35
+ #
36
+ # Enabling an automation whose contacts have been waiting more than an
37
+ # hour answers 409 `waiting_enrollments` (not retried) — the error's
38
+ # #waiting / #oldest say how many and since when. Repeat the call with
39
+ # `on_waiting:` "resume" (run their next step now) or "skip_waiting"
40
+ # (skip them; enable for new contacts only):
41
+ # Automations.update(id, { status: "enabled", on_waiting: "resume" })
33
42
  def update(automation_id, params)
34
43
  Client.request(:patch, "/automations/#{Client.path_escape(automation_id)}", body: params)
35
44
  end
@@ -72,12 +81,14 @@ module SendDart
72
81
  end
73
82
 
74
83
  # List an automation's runs. `status` filters to specific run statuses
75
- # ("running", "completed", "failed", "skipped") and accepts an Array or a
76
- # comma-separated String. GET /automations/:id/runs
84
+ # ("running", "completed", "failed", "skipped", "cancelled",
85
+ # "quota_exceeded") and accepts an Array or a comma-separated String;
86
+ # `created_after` / `created_before` (ISO 8601) bound the window. A bad
87
+ # status or date is a 422. GET /automations/:id/runs
77
88
  def runs(automation_id, params = {})
78
- query = Client.pagination(params)
79
- status = Client.opt(params, :status)
80
- query[:status] = status.is_a?(Array) ? status.join(",") : status unless status.nil?
89
+ query = Client.pagination(params).merge(
90
+ Client.list_filters(params, :status, :created_after, :created_before)
91
+ )
81
92
  Client.request(:get, "/automations/#{Client.path_escape(automation_id)}/runs", query: query)
82
93
  end
83
94
 
@@ -86,6 +97,18 @@ module SendDart
86
97
  Client.request(:get, "/automations/#{Client.path_escape(automation_id)}/runs/#{Client.path_escape(run_id)}")
87
98
  end
88
99
 
100
+ # Stop one running run; the contact leaves the flow at the step it was
101
+ # on. Returns { "object" => "automation_run", "id", "automation_id",
102
+ # "status", "cancelled" } — "cancelled", or the run's own status with
103
+ # "cancelled" => false when it had already finished.
104
+ # POST /automations/:id/runs/:run_id/cancel
105
+ def cancel_run(automation_id, run_id)
106
+ Client.request(
107
+ :post,
108
+ "/automations/#{Client.path_escape(automation_id)}/runs/#{Client.path_escape(run_id)}/cancel"
109
+ )
110
+ end
111
+
89
112
  # Stop an automation — no new runs; in-progress runs finish. POST /automations/:id/stop
90
113
  def stop(automation_id)
91
114
  Client.request(:post, "/automations/#{Client.path_escape(automation_id)}/stop")
@@ -95,6 +118,12 @@ module SendDart
95
118
  def delete(automation_id)
96
119
  Client.request(:delete, "/automations/#{Client.path_escape(automation_id)}")
97
120
  end
121
+
122
+ # Copy an automation with its steps. The copy starts `disabled`.
123
+ # POST /automations/:id/duplicate — returns the full new automation.
124
+ def duplicate(automation_id)
125
+ Client.request(:post, "/automations/#{Client.path_escape(automation_id)}/duplicate")
126
+ end
98
127
  end
99
128
  end
100
129
  end