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 +4 -4
- data/README.md +189 -23
- data/lib/senddart/account.rb +18 -0
- data/lib/senddart/api_keys.rb +29 -6
- data/lib/senddart/automations.rb +35 -6
- data/lib/senddart/campaigns.rb +123 -3
- data/lib/senddart/client.rb +28 -3
- data/lib/senddart/contacts.rb +24 -1
- data/lib/senddart/domains.rb +33 -0
- data/lib/senddart/emails.rb +51 -5
- data/lib/senddart/error.rb +38 -1
- data/lib/senddart/events.rb +7 -0
- data/lib/senddart/inboxes.rb +240 -0
- data/lib/senddart/pagination.rb +50 -0
- data/lib/senddart/response.rb +100 -0
- data/lib/senddart/segments.rb +14 -0
- data/lib/senddart/suppressions.rb +56 -0
- data/lib/senddart/templates.rb +5 -3
- data/lib/senddart/usage.rb +19 -0
- data/lib/senddart/version.rb +1 -1
- data/lib/senddart/webhooks.rb +40 -0
- data/lib/senddart.rb +17 -0
- metadata +8 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 833e007427682688d38465386e95f32bac7e88f9d2f2fbd9e29ce7d10039c8eb
|
|
4
|
+
data.tar.gz: 1ae32aeab81cb788eb4329694f4f725bc2353fc4f5d188091111ef83a415f5a2
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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: [
|
|
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 `
|
|
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
|
-
##
|
|
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::
|
|
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
|
-
`
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
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
|
data/lib/senddart/api_keys.rb
CHANGED
|
@@ -1,19 +1,42 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
module SendDart
|
|
4
|
-
#
|
|
5
|
-
#
|
|
6
|
-
#
|
|
7
|
-
#
|
|
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
|
data/lib/senddart/automations.rb
CHANGED
|
@@ -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"
|
|
76
|
-
# comma-separated String
|
|
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
|
-
|
|
80
|
-
|
|
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
|