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
data/lib/senddart/campaigns.rb
CHANGED
|
@@ -16,17 +16,18 @@ module SendDart
|
|
|
16
16
|
Client.request(:post, "/campaigns", body: params)
|
|
17
17
|
end
|
|
18
18
|
|
|
19
|
-
# GET /campaigns/:id
|
|
19
|
+
# GET /campaigns/:id (carries "updated_at")
|
|
20
20
|
def get(campaign_id)
|
|
21
21
|
Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}")
|
|
22
22
|
end
|
|
23
23
|
|
|
24
|
-
# GET /campaigns
|
|
24
|
+
# GET /campaigns (rows carry "updated_at")
|
|
25
25
|
def list(params = {})
|
|
26
26
|
Client.request(:get, "/campaigns", query: Client.pagination(params))
|
|
27
27
|
end
|
|
28
28
|
|
|
29
|
-
# PATCH /campaigns/:id
|
|
29
|
+
# PATCH /campaigns/:id. A `{ name: }`-only rename is accepted in any
|
|
30
|
+
# status; every other change is draft-only. Accepts the create-side
|
|
30
31
|
# fields plus `followups` (replace pending follow-ups, [] clears),
|
|
31
32
|
# `list_to` (true/false), `unsubscribe_policy` ("account" | "domain" |
|
|
32
33
|
# "ignore"), `schedule_timezone` (IANA zone; nil clears), and
|
|
@@ -76,6 +77,125 @@ module SendDart
|
|
|
76
77
|
def delete(campaign_id)
|
|
77
78
|
Client.request(:delete, "/campaigns/#{Client.path_escape(campaign_id)}")
|
|
78
79
|
end
|
|
80
|
+
|
|
81
|
+
# Copy any campaign (whatever its status) into a new DRAFT, follow-up
|
|
82
|
+
# rules included. POST /campaigns/:id/duplicate
|
|
83
|
+
# Returns { "object" => "campaign", "id", "name" }.
|
|
84
|
+
def duplicate(campaign_id)
|
|
85
|
+
Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/duplicate")
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
# Send the campaign to 1-5 addresses to check it in a real inbox.
|
|
89
|
+
# POST /campaigns/:id/test (send scope) — params: { to: } (an Array, or
|
|
90
|
+
# one String; a comma-separated String is accepted). The subject gets a
|
|
91
|
+
# "[Test] " prefix, merge tags render sample/fallback values, and the
|
|
92
|
+
# campaign's status is unchanged. Pass { idempotency_key: "..." } as the
|
|
93
|
+
# third argument so a double submit cannot send twice.
|
|
94
|
+
# Returns { "object" => "email", "id", "to" => [...] }.
|
|
95
|
+
def test(campaign_id, params, options = {})
|
|
96
|
+
Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/test", body: params, options: options)
|
|
97
|
+
end
|
|
98
|
+
|
|
99
|
+
# Save the campaign's content as a new DRAFT template (422
|
|
100
|
+
# validation_error when the campaign has no content).
|
|
101
|
+
# POST /campaigns/:id/template — returns { "object" => "template", "id", "name" }.
|
|
102
|
+
def save_as_template(campaign_id)
|
|
103
|
+
Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/template")
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
# Resume a campaign the server `paused` (reputation or limit pause) once
|
|
107
|
+
# its checks pass. POST /campaigns/:id/continue (send scope)
|
|
108
|
+
# Returns { "id", "status" => "queued", "remaining" => Integer }. A 409
|
|
109
|
+
# validation_error means it is not paused, changed, or has nothing left;
|
|
110
|
+
# a 429 carries daily_quota_exceeded / plan-limit / reputation names.
|
|
111
|
+
# (`continue` is a Ruby keyword, hence the name.)
|
|
112
|
+
def continue_sending(campaign_id)
|
|
113
|
+
Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/continue")
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
# Recipients of this campaign that are now bounced.
|
|
117
|
+
# GET /campaigns/:id/bounced-contacts — { "count", "sample" (up to 25
|
|
118
|
+
# emails), "version" (64-hex) }. Pass `version` to remove_bounced_contacts.
|
|
119
|
+
def bounced_contacts(campaign_id)
|
|
120
|
+
Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/bounced-contacts")
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
# Remove the bounced contacts counted by bounced_contacts.
|
|
124
|
+
# POST /campaigns/:id/bounced-contacts — params: { version: } (from
|
|
125
|
+
# bounced_contacts). Returns { "removed" => Integer }. A 409
|
|
126
|
+
# validation_error means the list changed since — fetch it again.
|
|
127
|
+
def remove_bounced_contacts(campaign_id, params)
|
|
128
|
+
Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/bounced-contacts", body: params)
|
|
129
|
+
end
|
|
130
|
+
|
|
131
|
+
# Batch-by-batch send history. GET /campaigns/:id/batches
|
|
132
|
+
# Returns { "remaining_count", "current_batch_id", "can_send",
|
|
133
|
+
# "history_complete", "in_progress", "data" => [{ "id",
|
|
134
|
+
# "requested_count", "selected_count", "created_at", "attempted_count",
|
|
135
|
+
# "sent_count", "failed_count" }] } — newest first, at most 100, and NOT
|
|
136
|
+
# a paginated list (no "object"/"has_more").
|
|
137
|
+
def batches(campaign_id)
|
|
138
|
+
Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/batches")
|
|
139
|
+
end
|
|
140
|
+
|
|
141
|
+
# Add a follow-up to a `sending`/`sent` campaign (at most 5 active).
|
|
142
|
+
# POST /campaigns/:id/followups (write + send scope) — params:
|
|
143
|
+
# { condition: "delivered" | "opened" | "clicked" | "replied",
|
|
144
|
+
# delay_days: 0-7, delay_hours: 0-23, html: "...",
|
|
145
|
+
# subject: "..." (omit or "" to reuse the campaign's),
|
|
146
|
+
# auto_followup: true | false }
|
|
147
|
+
# Returns { "object" => "campaign_followup", "id", "recipients" }.
|
|
148
|
+
def create_followup(campaign_id, params)
|
|
149
|
+
Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/followups", body: params)
|
|
150
|
+
end
|
|
151
|
+
|
|
152
|
+
# GET /campaigns/:id/followups/:followup_id — the follow-up with its
|
|
153
|
+
# "condition", "delay_days", "delay_hours", "subject", "html", "status",
|
|
154
|
+
# "mode" ("manual" | "auto"), "run_at", "sent_count", "active" and
|
|
155
|
+
# "delivery_counts" ({ "pending", "sending", "sent", "failed", "canceled" }).
|
|
156
|
+
def get_followup(campaign_id, followup_id)
|
|
157
|
+
Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/followups/#{Client.path_escape(followup_id)}")
|
|
158
|
+
end
|
|
159
|
+
|
|
160
|
+
# Replace a follow-up. PATCH /campaigns/:id/followups/:followup_id
|
|
161
|
+
# Takes the FULL create_followup params again (validated the same way)
|
|
162
|
+
# plus optional `resend_previously_sent: true`.
|
|
163
|
+
# Returns { "object" => "campaign_followup", "id", "recipients" }.
|
|
164
|
+
def update_followup(campaign_id, followup_id, params)
|
|
165
|
+
Client.request(
|
|
166
|
+
:patch,
|
|
167
|
+
"/campaigns/#{Client.path_escape(campaign_id)}/followups/#{Client.path_escape(followup_id)}",
|
|
168
|
+
body: params
|
|
169
|
+
)
|
|
170
|
+
end
|
|
171
|
+
|
|
172
|
+
# One page of the people the campaign went to, optionally only one
|
|
173
|
+
# outcome. GET /campaigns/:id/recipients — params: { type: ("delivered",
|
|
174
|
+
# "opened", "clicked", "bounced", "complained", "failed", "suppressed"),
|
|
175
|
+
# limit: (1-100, 20), after: (the last row's "id") }. Rows: { "object" =>
|
|
176
|
+
# "campaign_recipient", "id", "email", "contact_id", "status",
|
|
177
|
+
# "sent_at", "opened_at", "clicked_at", "open_count", "click_count" }.
|
|
178
|
+
# Marketing analytics: paid marketing plans only.
|
|
179
|
+
def recipients(campaign_id, params = {})
|
|
180
|
+
query = Client.filters(params, :type, :limit, :after)
|
|
181
|
+
Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/recipients", query: query)
|
|
182
|
+
end
|
|
183
|
+
|
|
184
|
+
# Every tracked link with its click total, most-clicked first:
|
|
185
|
+
# { "object" => "list", "data" => [{ "object" => "campaign_link", "url",
|
|
186
|
+
# "clicks" }] }. GET /campaigns/:id/clicked-links — params: { limit:
|
|
187
|
+
# (1-100, 50) }. Marketing analytics: paid marketing plans only.
|
|
188
|
+
def clicked_links(campaign_id, params = {})
|
|
189
|
+
query = Client.filters(params, :limit)
|
|
190
|
+
Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/clicked-links", query: query)
|
|
191
|
+
end
|
|
192
|
+
|
|
193
|
+
# Cancel a follow-up (it is not hard-deleted).
|
|
194
|
+
# DELETE /campaigns/:id/followups/:followup_id
|
|
195
|
+
# Returns { "object" => "campaign_followup", "id", "canceled" => true }.
|
|
196
|
+
def delete_followup(campaign_id, followup_id)
|
|
197
|
+
Client.request(:delete, "/campaigns/#{Client.path_escape(campaign_id)}/followups/#{Client.path_escape(followup_id)}")
|
|
198
|
+
end
|
|
79
199
|
end
|
|
80
200
|
end
|
|
81
201
|
end
|
data/lib/senddart/client.rb
CHANGED
|
@@ -16,6 +16,7 @@ module SendDart
|
|
|
16
16
|
get: Net::HTTP::Get,
|
|
17
17
|
post: Net::HTTP::Post,
|
|
18
18
|
patch: Net::HTTP::Patch,
|
|
19
|
+
put: Net::HTTP::Put,
|
|
19
20
|
delete: Net::HTTP::Delete
|
|
20
21
|
}.freeze
|
|
21
22
|
|
|
@@ -36,10 +37,17 @@ module SendDart
|
|
|
36
37
|
# the server be the authority.
|
|
37
38
|
IDEMPOTENCY_KEY_MAX_LENGTH = 255
|
|
38
39
|
|
|
40
|
+
# Thread.current key behind SendDart.last_response. Thread.current[] is
|
|
41
|
+
# fiber-local, so concurrent threads (and fibers) never see each other's.
|
|
42
|
+
LAST_RESPONSE_KEY = :senddart_last_response
|
|
43
|
+
|
|
39
44
|
# Perform an API request and return the parsed JSON body (a Hash/Array),
|
|
40
45
|
# or the raw body String when `raw: true` (binary download endpoints).
|
|
41
46
|
# Raises SendDart::Error on any non-2xx response.
|
|
42
47
|
def request(verb, path, body: nil, query: nil, options: {}, raw: false)
|
|
48
|
+
# Cleared first, so a call that fails without a response (missing key,
|
|
49
|
+
# network error) never leaves an older call's headers behind.
|
|
50
|
+
Thread.current[LAST_RESPONSE_KEY] = nil
|
|
43
51
|
key = SendDart.api_key
|
|
44
52
|
if key.nil? || key.to_s.strip.empty?
|
|
45
53
|
raise SendDart::Error.new(
|
|
@@ -54,7 +62,16 @@ module SendDart
|
|
|
54
62
|
end
|
|
55
63
|
|
|
56
64
|
req = build_request(verb, uri, body, options, key)
|
|
57
|
-
|
|
65
|
+
resp = deliver_with_retries(req, uri)
|
|
66
|
+
handle_response(resp, raw: raw, response: record_response(resp))
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
# Snapshot the final attempt's status + headers as a SendDart::Response
|
|
70
|
+
# and publish it as SendDart.last_response for the current thread.
|
|
71
|
+
def record_response(resp)
|
|
72
|
+
response = Response.from_http(resp)
|
|
73
|
+
Thread.current[LAST_RESPONSE_KEY] = response
|
|
74
|
+
response
|
|
58
75
|
end
|
|
59
76
|
|
|
60
77
|
# The single request chokepoint: both the JSON and raw/binary paths funnel
|
|
@@ -166,7 +183,7 @@ module SendDart
|
|
|
166
183
|
end
|
|
167
184
|
end
|
|
168
185
|
|
|
169
|
-
def handle_response(resp, raw: false)
|
|
186
|
+
def handle_response(resp, raw: false, response: nil)
|
|
170
187
|
code = resp.code.to_i
|
|
171
188
|
body = resp.body
|
|
172
189
|
|
|
@@ -193,7 +210,8 @@ module SendDart
|
|
|
193
210
|
parsed["message"] || "Request failed with status #{code}",
|
|
194
211
|
status_code: code,
|
|
195
212
|
error_name: parsed["name"] || "application_error",
|
|
196
|
-
body: parsed
|
|
213
|
+
body: parsed,
|
|
214
|
+
response: response
|
|
197
215
|
)
|
|
198
216
|
end
|
|
199
217
|
end
|
|
@@ -251,6 +269,13 @@ module SendDart
|
|
|
251
269
|
end
|
|
252
270
|
end
|
|
253
271
|
|
|
272
|
+
# Like `filters`, for list endpoints that take comma lists: an Array value
|
|
273
|
+
# is sent comma-separated (`statuses`, `dimensions`, `from`...) instead
|
|
274
|
+
# of as a repeated key.
|
|
275
|
+
def list_filters(params, *keys)
|
|
276
|
+
filters(params, *keys).transform_values { |v| v.is_a?(Array) ? v.join(",") : v }
|
|
277
|
+
end
|
|
278
|
+
|
|
254
279
|
# Domain-first guard: several resources require the sending domain.
|
|
255
280
|
def require_domain!(params, context)
|
|
256
281
|
v = opt(params, :domain)
|
data/lib/senddart/contacts.rb
CHANGED
|
@@ -122,11 +122,15 @@ module SendDart
|
|
|
122
122
|
# Or a file already uploaded via create_import_upload (no row cap — the
|
|
123
123
|
# overflow past your contact limit comes back as `limit_skipped`):
|
|
124
124
|
# Contacts.import({ audience_id: "aud_1", storage_key: key })
|
|
125
|
+
# `mapping` maps CSV headers to fields: { "E-mail" => "email", "Notes" =>
|
|
126
|
+
# "ignore", "Company" => "company" } — "email", "first_name",
|
|
127
|
+
# "last_name", "unsubscribed", "ignore" or a property key; one column
|
|
128
|
+
# must be email and a field is used once.
|
|
125
129
|
def import(params)
|
|
126
130
|
audience_id = Client.opt(params, :audience_id)
|
|
127
131
|
query = Client.filters(params, :on_conflict, :segment_id)
|
|
128
132
|
query[:create_properties] = "false" if Client.opt(params, :create_properties) == false
|
|
129
|
-
body = Client.filters(params, :csv, :file_name, :storage_key)
|
|
133
|
+
body = Client.filters(params, :csv, :file_name, :storage_key, :mapping)
|
|
130
134
|
Client.request(
|
|
131
135
|
:post,
|
|
132
136
|
"/audiences/#{Client.path_escape(audience_id)}/contacts/import",
|
|
@@ -149,6 +153,25 @@ module SendDart
|
|
|
149
153
|
)
|
|
150
154
|
end
|
|
151
155
|
|
|
156
|
+
# Dry-run an uploaded CSV before importing it: nothing is written.
|
|
157
|
+
# POST /audiences/:id/contacts/import/preview — params:
|
|
158
|
+
# { audience_id:, storage_key:, mapping: } (the key from
|
|
159
|
+
# create_import_upload, after you PUT the file; `mapping` as in
|
|
160
|
+
# `import`). Returns { "object" => "contact_import_preview", "file_name",
|
|
161
|
+
# "size_bytes", "has_header", "header_row", "header_is_data", "mapping",
|
|
162
|
+
# "columns", "property_keys", "source_rows", "valid_rows",
|
|
163
|
+
# "unique_contacts", "duplicate_rows", "invalid_rows",
|
|
164
|
+
# "existing_contacts", "new_contacts", "sample" (up to 20 parsed
|
|
165
|
+
# contacts), "warnings" }.
|
|
166
|
+
def preview_import(params)
|
|
167
|
+
audience_id = Client.opt(params, :audience_id)
|
|
168
|
+
Client.request(
|
|
169
|
+
:post,
|
|
170
|
+
"/audiences/#{Client.path_escape(audience_id)}/contacts/import/preview",
|
|
171
|
+
body: Client.without(params, :audience_id)
|
|
172
|
+
)
|
|
173
|
+
end
|
|
174
|
+
|
|
152
175
|
# Add a contact to a segment. POST /contacts/:id/segments/:segment_id
|
|
153
176
|
def add_to_segment(contact_id, segment_id)
|
|
154
177
|
Client.request(:post, "/contacts/#{Client.path_escape(contact_id)}/segments/#{Client.path_escape(segment_id)}")
|
data/lib/senddart/domains.rb
CHANGED
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
module SendDart
|
|
4
4
|
module Domains
|
|
5
|
+
# The deprecation message every retired DNS auto-setup method prints.
|
|
6
|
+
DNS_SETUP_DEPRECATION = "Automatic DNS setup was retired on 2026-10-15; the API now answers 410 " \
|
|
7
|
+
"dns_setup_disabled. Add the records from Domains.get / Domains.records_csv at your " \
|
|
8
|
+
"DNS provider. This method will be removed in 2.0."
|
|
9
|
+
|
|
5
10
|
class << self
|
|
6
11
|
# HTTPS readiness; an unavailable host schedules server-side repair.
|
|
7
12
|
def tracking_health(domain_id)
|
|
@@ -67,19 +72,34 @@ module SendDart
|
|
|
67
72
|
|
|
68
73
|
# Detect the DNS provider and available one-click apply methods.
|
|
69
74
|
# GET /domains/:id/dns/detect
|
|
75
|
+
#
|
|
76
|
+
# @deprecated Automatic DNS setup was retired on 2026-10-15; the API now
|
|
77
|
+
# answers 410 dns_setup_disabled. Add the records from Domains.get /
|
|
78
|
+
# Domains.records_csv at your DNS provider. Removed in 2.0.
|
|
70
79
|
def detect_dns(domain_id)
|
|
80
|
+
warn_dns_deprecated(:detect_dns)
|
|
71
81
|
Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/dns/detect")
|
|
72
82
|
end
|
|
73
83
|
|
|
74
84
|
# Apply DNS records via the Cloudflare API, then auto-verify.
|
|
75
85
|
# POST /domains/:id/dns/cloudflare — params: { token: "..." }
|
|
86
|
+
#
|
|
87
|
+
# @deprecated Automatic DNS setup was retired on 2026-10-15; the API now
|
|
88
|
+
# answers 410 dns_setup_disabled. Add the records from Domains.get /
|
|
89
|
+
# Domains.records_csv at your DNS provider. Removed in 2.0.
|
|
76
90
|
def apply_cloudflare_dns(domain_id, params)
|
|
91
|
+
warn_dns_deprecated(:apply_cloudflare_dns)
|
|
77
92
|
Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/cloudflare", body: params)
|
|
78
93
|
end
|
|
79
94
|
|
|
80
95
|
# Apply DNS records via the GoDaddy API, then auto-verify.
|
|
81
96
|
# POST /domains/:id/dns/godaddy — params: { key: "...", secret: "..." }
|
|
97
|
+
#
|
|
98
|
+
# @deprecated Automatic DNS setup was retired on 2026-10-15; the API now
|
|
99
|
+
# answers 410 dns_setup_disabled. Add the records from Domains.get /
|
|
100
|
+
# Domains.records_csv at your DNS provider. Removed in 2.0.
|
|
82
101
|
def apply_godaddy_dns(domain_id, params)
|
|
102
|
+
warn_dns_deprecated(:apply_godaddy_dns)
|
|
83
103
|
Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/godaddy", body: params)
|
|
84
104
|
end
|
|
85
105
|
|
|
@@ -90,7 +110,12 @@ module SendDart
|
|
|
90
110
|
# are accepted aliases, and the optional username may also be spelled
|
|
91
111
|
# `username`, but there is NO `user_name` alias: the API ignores that key,
|
|
92
112
|
# so a username sent under it is silently dropped.
|
|
113
|
+
#
|
|
114
|
+
# @deprecated Automatic DNS setup was retired on 2026-10-15; the API now
|
|
115
|
+
# answers 410 dns_setup_disabled. Add the records from Domains.get /
|
|
116
|
+
# Domains.records_csv at your DNS provider. Removed in 2.0.
|
|
93
117
|
def apply_namecheap_dns(domain_id, params)
|
|
118
|
+
warn_dns_deprecated(:apply_namecheap_dns)
|
|
94
119
|
Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/namecheap", body: params)
|
|
95
120
|
end
|
|
96
121
|
|
|
@@ -98,6 +123,14 @@ module SendDart
|
|
|
98
123
|
def delete(domain_id)
|
|
99
124
|
Client.request(:delete, "/domains/#{Client.path_escape(domain_id)}")
|
|
100
125
|
end
|
|
126
|
+
|
|
127
|
+
private
|
|
128
|
+
|
|
129
|
+
# Kernel#warn goes to $stderr and is silenced by `ruby -W0` ($VERBOSE nil).
|
|
130
|
+
# The request still goes out, so existing callers keep working until 2.0.
|
|
131
|
+
def warn_dns_deprecated(method_name)
|
|
132
|
+
warn "[DEPRECATION] SendDart::Domains.#{method_name} is deprecated. #{DNS_SETUP_DEPRECATION}"
|
|
133
|
+
end
|
|
101
134
|
end
|
|
102
135
|
end
|
|
103
136
|
end
|
data/lib/senddart/emails.rb
CHANGED
|
@@ -36,10 +36,23 @@ module SendDart
|
|
|
36
36
|
# against the row's `last_event`), `folder` (one of "outbox", "sent",
|
|
37
37
|
# "scheduled" or "failed" — any other value is rejected with a 422) and
|
|
38
38
|
# `search` (recipients, subject and sender). `q` is the server's alias
|
|
39
|
-
# for `search`, honoured only when `search` is absent.
|
|
39
|
+
# for `search`, honoured only when `search` is absent.
|
|
40
|
+
# Also: `engagement` ("delivered", "opened", "clicked", "replied",
|
|
41
|
+
# "bounced" or "complained"), `campaign_scope` ("direct" — one-off sends
|
|
42
|
+
# only, no campaign mail), and `created_after` / `created_before` (ISO
|
|
43
|
+
# 8601 date-times such as "2026-01-31T00:00:00Z"; after must be earlier
|
|
44
|
+
# than before, and a malformed value is a 422). They are `created_*`
|
|
45
|
+
# because `after`/`before` are the pagination cursors.
|
|
46
|
+
# `statuses` (an Array or comma list of bounced, canceled, clicked,
|
|
47
|
+
# complained, delivered, delivery_delayed, failed, opened, queued,
|
|
48
|
+
# replied, scheduled, sent, suppressed — merged with `status`; an unknown
|
|
49
|
+
# one is a 422), `api_key_id` (the key that sent it) and `query` (alias
|
|
50
|
+
# of `search`) narrow it further. GET /emails
|
|
40
51
|
def list(params = {})
|
|
41
52
|
query = Client.pagination(params).merge(
|
|
42
|
-
Client.
|
|
53
|
+
Client.list_filters(params, :campaign_id, :automation_id, :source, :domain_id, :status, :statuses,
|
|
54
|
+
:api_key_id, :search, :query, :q, :folder, :engagement, :campaign_scope,
|
|
55
|
+
:created_after, :created_before)
|
|
43
56
|
)
|
|
44
57
|
Client.request(:get, "/emails", query: query)
|
|
45
58
|
end
|
|
@@ -53,6 +66,28 @@ module SendDart
|
|
|
53
66
|
Client.request(:get, "/emails/sources")
|
|
54
67
|
end
|
|
55
68
|
|
|
69
|
+
# What happened to the account's email over a window of UTC days.
|
|
70
|
+
# GET /emails/metrics — params: { start_date:, end_date: (YYYY-MM-DD;
|
|
71
|
+
# default the last 7 days, at most 92), dimensions: (Array or comma list
|
|
72
|
+
# of "period", "domain", "campaign"), domain_id:, campaign_id: (Array or
|
|
73
|
+
# comma list) }. Returns { "object" => "list", "start_date", "end_date",
|
|
74
|
+
# "dimensions", "data" => [{ "period"?, "domain_id"?, "campaign_id"?,
|
|
75
|
+
# "sent", "delivered", "delivery_delayed", "opened", "clicked",
|
|
76
|
+
# "bounced", "complained", "failed" }] }.
|
|
77
|
+
def metrics(params = {})
|
|
78
|
+
query = Client.list_filters(params, :start_date, :end_date, :dimensions, :domain_id, :campaign_id,
|
|
79
|
+
:broadcast_id)
|
|
80
|
+
Client.request(:get, "/emails/metrics", query: query)
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
# Create a public, read-only link to one sent email, valid 48 hours (a
|
|
84
|
+
# new link revokes the previous one; the URL is only in this answer).
|
|
85
|
+
# Needs write access. Returns { "object" => "email_share", "email_id",
|
|
86
|
+
# "url", "expires_at" }. POST /emails/:id/share
|
|
87
|
+
def share(email_id)
|
|
88
|
+
Client.request(:post, "/emails/#{Client.path_escape(email_id)}/share")
|
|
89
|
+
end
|
|
90
|
+
|
|
56
91
|
# Retrieve a sent email and its events. GET /emails/:id
|
|
57
92
|
def get(email_id)
|
|
58
93
|
Client.request(:get, "/emails/#{Client.path_escape(email_id)}")
|
|
@@ -83,13 +118,17 @@ module SendDart
|
|
|
83
118
|
# Inbound (received) email.
|
|
84
119
|
module Receiving
|
|
85
120
|
class << self
|
|
86
|
-
# List received emails — cursor pagination plus
|
|
87
|
-
# `received_for`
|
|
121
|
+
# List received emails — cursor pagination plus optional filters:
|
|
122
|
+
# `received_for` (only messages received for that address), `search`
|
|
123
|
+
# (or its alias `query`) and `created_after` / `created_before` (ISO
|
|
124
|
+
# 8601; a malformed date is a 422).
|
|
88
125
|
# With no `limit` and no cursor the endpoint returns up to 1000 rows in
|
|
89
126
|
# one response; pass `limit` to get normal 1-100 pages.
|
|
90
127
|
# GET /emails/receiving
|
|
91
128
|
def list(params = {})
|
|
92
|
-
query = Client.pagination(params).merge(
|
|
129
|
+
query = Client.pagination(params).merge(
|
|
130
|
+
Client.filters(params, :received_for, :search, :query, :created_after, :created_before)
|
|
131
|
+
)
|
|
93
132
|
Client.request(:get, "/emails/receiving", query: query)
|
|
94
133
|
end
|
|
95
134
|
|
|
@@ -104,6 +143,13 @@ module SendDart
|
|
|
104
143
|
Client.request(:get, "/emails/receiving/#{Client.path_escape(email_id)}")
|
|
105
144
|
end
|
|
106
145
|
|
|
146
|
+
# Mark a received email read or unread (write scope).
|
|
147
|
+
# PATCH /emails/receiving/:id — params: { read: true | false }
|
|
148
|
+
# Returns the full received email, including "read" and "read_at".
|
|
149
|
+
def update(email_id, params)
|
|
150
|
+
Client.request(:patch, "/emails/receiving/#{Client.path_escape(email_id)}", body: params)
|
|
151
|
+
end
|
|
152
|
+
|
|
107
153
|
# List a received email's attachments. With no `limit` and no `after`
|
|
108
154
|
# one page carries up to 1,000 of them and `has_more` reports any
|
|
109
155
|
# truncation; supplying either paginates normally.
|
data/lib/senddart/error.rb
CHANGED
|
@@ -30,6 +30,8 @@ module SendDart
|
|
|
30
30
|
# e.reputation # reputation gates
|
|
31
31
|
# e.sent # a batch that failed part way through
|
|
32
32
|
# e.sent_count # — do NOT resend these
|
|
33
|
+
# e.waiting; e.oldest # 409 waiting_enrollments
|
|
34
|
+
# e.rate_limit&.retry_after # parsed response headers
|
|
33
35
|
# end
|
|
34
36
|
class Error < StandardError
|
|
35
37
|
attr_reader :status_code, :error_name
|
|
@@ -38,11 +40,46 @@ module SendDart
|
|
|
38
40
|
# Read it for any additive field newer than this SDK version.
|
|
39
41
|
attr_reader :body
|
|
40
42
|
|
|
41
|
-
|
|
43
|
+
# The SendDart::Response (status + headers) of the failed request, or nil
|
|
44
|
+
# for an error raised before any request went out (e.g. missing_api_key).
|
|
45
|
+
attr_reader :response
|
|
46
|
+
|
|
47
|
+
def initialize(message = nil, status_code: nil, error_name: nil, body: nil, response: nil)
|
|
42
48
|
super(message)
|
|
43
49
|
@status_code = status_code
|
|
44
50
|
@error_name = error_name
|
|
45
51
|
@body = body.is_a?(Hash) ? body : {}
|
|
52
|
+
@response = response
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
# The failed response's headers (lower-cased keys), {} when there was none.
|
|
56
|
+
def headers
|
|
57
|
+
@response ? @response.headers : {}
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
# The parsed RateLimit-* / Retry-After headers (a SendDart::RateLimit),
|
|
61
|
+
# or nil when there was no response. Most useful on a 429:
|
|
62
|
+
#
|
|
63
|
+
# rescue SendDart::Error => e
|
|
64
|
+
# sleep(e.rate_limit.retry_after || 1) if e.status_code == 429
|
|
65
|
+
def rate_limit
|
|
66
|
+
@response&.rate_limit
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
# How many contacts are waiting, on a 409 `waiting_enrollments` (enabling
|
|
70
|
+
# an automation whose contacts have waited over an hour), else nil.
|
|
71
|
+
# Repeat Automations.update with `on_waiting: "resume"` (run their next
|
|
72
|
+
# step now) or `"skip_waiting"` (skip them; enable for new contacts only).
|
|
73
|
+
def waiting
|
|
74
|
+
value = @body["waiting"]
|
|
75
|
+
value.is_a?(Integer) ? value : nil
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
# ISO 8601 time the longest-waiting contact started waiting, on a 409
|
|
79
|
+
# `waiting_enrollments`, else nil (also nil when the API sent null).
|
|
80
|
+
def oldest
|
|
81
|
+
value = @body["oldest"]
|
|
82
|
+
value.is_a?(String) ? value : nil
|
|
46
83
|
end
|
|
47
84
|
|
|
48
85
|
# The API error `name` (e.g. "validation_error", "not_found").
|
data/lib/senddart/events.rb
CHANGED
|
@@ -39,6 +39,13 @@ module SendDart
|
|
|
39
39
|
Client.request(:patch, "/events/#{Client.path_escape(event_id)}", body: params)
|
|
40
40
|
end
|
|
41
41
|
|
|
42
|
+
# One custom-event definition by its id OR its name: { "object" =>
|
|
43
|
+
# "event", "id", "name", "schema", "created_at", "updated_at" }.
|
|
44
|
+
# GET /events/:id
|
|
45
|
+
def get(event_id)
|
|
46
|
+
Client.request(:get, "/events/#{Client.path_escape(event_id)}")
|
|
47
|
+
end
|
|
48
|
+
|
|
42
49
|
# List custom-event definitions. GET /events
|
|
43
50
|
def list(params = {})
|
|
44
51
|
Client.request(:get, "/events", query: Client.pagination(params))
|