senddart 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. senddart-1.0.0/LICENSE +21 -0
  2. senddart-1.0.0/MANIFEST.in +1 -0
  3. senddart-1.0.0/PKG-INFO +457 -0
  4. senddart-1.0.0/README.md +430 -0
  5. senddart-1.0.0/pyproject.toml +35 -0
  6. senddart-1.0.0/senddart/__init__.py +80 -0
  7. senddart-1.0.0/senddart/api_keys.py +21 -0
  8. senddart-1.0.0/senddart/audiences.py +56 -0
  9. senddart-1.0.0/senddart/automations.py +175 -0
  10. senddart-1.0.0/senddart/batch.py +40 -0
  11. senddart-1.0.0/senddart/campaigns.py +128 -0
  12. senddart-1.0.0/senddart/contact_properties.py +50 -0
  13. senddart-1.0.0/senddart/contacts.py +256 -0
  14. senddart-1.0.0/senddart/domains.py +140 -0
  15. senddart-1.0.0/senddart/emails.py +296 -0
  16. senddart-1.0.0/senddart/events.py +75 -0
  17. senddart-1.0.0/senddart/exceptions.py +109 -0
  18. senddart-1.0.0/senddart/http_client.py +295 -0
  19. senddart-1.0.0/senddart/logs.py +41 -0
  20. senddart-1.0.0/senddart/polls.py +18 -0
  21. senddart-1.0.0/senddart/segments.py +86 -0
  22. senddart-1.0.0/senddart/templates.py +89 -0
  23. senddart-1.0.0/senddart/topics.py +71 -0
  24. senddart-1.0.0/senddart/webhooks.py +292 -0
  25. senddart-1.0.0/senddart.egg-info/PKG-INFO +457 -0
  26. senddart-1.0.0/senddart.egg-info/SOURCES.txt +39 -0
  27. senddart-1.0.0/senddart.egg-info/dependency_links.txt +1 -0
  28. senddart-1.0.0/senddart.egg-info/top_level.txt +1 -0
  29. senddart-1.0.0/setup.cfg +4 -0
  30. senddart-1.0.0/tests/__init__.py +0 -0
  31. senddart-1.0.0/tests/fixtures/http-recovery-corpus.json +19 -0
  32. senddart-1.0.0/tests/helpers.py +50 -0
  33. senddart-1.0.0/tests/test_campaigns.py +58 -0
  34. senddart-1.0.0/tests/test_contacts.py +162 -0
  35. senddart-1.0.0/tests/test_domains.py +59 -0
  36. senddart-1.0.0/tests/test_emails.py +139 -0
  37. senddart-1.0.0/tests/test_http_client.py +447 -0
  38. senddart-1.0.0/tests/test_misc_resources.py +183 -0
  39. senddart-1.0.0/tests/test_recovery.py +105 -0
  40. senddart-1.0.0/tests/test_segments.py +57 -0
  41. senddart-1.0.0/tests/test_webhooks.py +465 -0
senddart-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SendDart
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ recursive-include tests *.py *.json
@@ -0,0 +1,457 @@
1
+ Metadata-Version: 2.4
2
+ Name: senddart
3
+ Version: 1.0.0
4
+ Summary: Official SendDart Python SDK — send transactional and marketing email from your own verified domain.
5
+ Author: SendDart
6
+ License: MIT
7
+ Project-URL: Homepage, https://www.senddart.com
8
+ Project-URL: Documentation, https://www.senddart.com/docs
9
+ Project-URL: Repository, https://github.com/shekhu10/senddart-sdks
10
+ Keywords: senddart,email,transactional,marketing,smtp
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.8
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Topic :: Communications :: Email
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Requires-Python: >=3.8
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Dynamic: license-file
27
+
28
+ # senddart
29
+
30
+ Official Python SDK for the [SendDart](https://www.senddart.com) email API — send transactional and marketing email from your own verified domain.
31
+
32
+ Zero dependencies (Python standard library only). Python 3.8+.
33
+
34
+ ## Install
35
+
36
+ ```bash
37
+ pip install senddart
38
+ ```
39
+
40
+ ## Setup
41
+
42
+ Grab your API key from the [SendDart dashboard](https://www.senddart.com).
43
+
44
+ ```python
45
+ import senddart
46
+
47
+ senddart.api_key = "mb_xxxxxxxxx"
48
+ ```
49
+
50
+ ## Send your first email
51
+
52
+ ```python
53
+ import senddart
54
+
55
+ senddart.api_key = "mb_xxxxxxxxx"
56
+
57
+ params: senddart.Emails.SendParams = {
58
+ "from": "Acme <hello@yourdomain.com>",
59
+ "to": ["delivered@test.senddart.com"],
60
+ "subject": "Hello from SendDart",
61
+ "html": "<p>Your first email 🎉</p>",
62
+ }
63
+
64
+ email = senddart.Emails.send(params)
65
+ print(email["id"])
66
+ ```
67
+
68
+ Every method returns the parsed JSON response — except the three binary
69
+ download helpers (`Emails.Receiving.get_attachment`, `Emails.Receiving.get_raw`
70
+ and `Domains.records_csv`), which return `bytes`. On any non-2xx status the SDK
71
+ raises `senddart.SendDartError` carrying the API error body:
72
+
73
+ ```python
74
+ try:
75
+ senddart.Emails.send(params)
76
+ except senddart.SendDartError as e:
77
+ print(e.status_code, e.name, e.message) # e.g. 422 validation_error "..."
78
+ ```
79
+
80
+ ### Attachments
81
+
82
+ Attach files by hosted URL (`path`, fetched at send time) or inline base64 (`content`):
83
+
84
+ ```python
85
+ senddart.Emails.send({
86
+ "from": "Acme <hello@yourdomain.com>",
87
+ "to": ["delivered@test.senddart.com"],
88
+ "subject": "Your invoice",
89
+ "html": "<p>Invoice attached.</p>",
90
+ "attachments": [
91
+ {"filename": "invoice.pdf", "path": "https://yourdomain.com/invoices/invoice.pdf"},
92
+ {"filename": "report.csv", "content": base64_content, "content_type": "text/csv"},
93
+ ],
94
+ })
95
+ ```
96
+
97
+ ### Batch send
98
+
99
+ ```python
100
+ senddart.Batch.send([
101
+ {"from": "hello@yourdomain.com", "to": ["delivered@test.senddart.com"], "subject": "Hi A", "html": "<p>A</p>"},
102
+ {"from": "hello@yourdomain.com", "to": ["delivered@test.senddart.com"], "subject": "Hi B", "html": "<p>B</p>"},
103
+ ]) # up to 100 emails per request
104
+ ```
105
+
106
+ A batch succeeds in one of two ways, chosen by its **size** alone — branch on
107
+ `queued`, not on the absence of an error:
108
+
109
+ | Batch size | Status | Response | What happened |
110
+ |---|---|---|---|
111
+ | 1–40 | `200` | no `queued` key at all — never `queued: False` | every id in `data` is already handed to the mail service |
112
+ | 41–100 | `202` | `queued: True`, `queued_count == len(result["data"])` | ids are real, but the emails are still `scheduled` — **nothing has been transmitted yet** |
113
+
114
+ ```python
115
+ result = senddart.Batch.send(payloads)
116
+ if result.get("queued"):
117
+ # Accepted, not sent. Poll senddart.Emails.get(id) for the outcome.
118
+ ...
119
+ ```
120
+
121
+ Queuing is the only way the documented 100-email maximum can be accepted at all:
122
+ 100 inline sends run past the platform's request ceiling. A batch carrying an
123
+ `@test.senddart.com` simulator recipient in `to`, `cc` or `bcc` stays inline at any
124
+ size. An inline batch near the 40-email boundary can take ~100s server-side, far
125
+ past the 30s default `senddart.timeout` — raise it for batches that large, and
126
+ always pass an `idempotency_key`, since a client that gives up mid-request cannot
127
+ tell what was already sent.
128
+
129
+ ### Options
130
+
131
+ ```python
132
+ senddart.base_url = "https://www.senddart.com/api" # override your API host
133
+ senddart.timeout = 30 # per-request timeout in seconds (default 30)
134
+ senddart.max_retries = 2 # auto-retry 429/503 responses (default 2; 0 disables)
135
+ ```
136
+
137
+ Requests time out after 30 seconds by default. Automatic retries consider only HTTP 429 and 503 and honor `Retry-After`
138
+ (with capped exponential backoff otherwise). Partial or uncertain results stop
139
+ immediately. Generic 503 responses retry only reads or a send protected by an
140
+ operation key; other writes need a documented rejection before processing.
141
+ Network errors, timeouts, 409, 422, and other 5xx responses are never retried.
142
+ See **Recovery and tracking contracts** below before retrying in application code.
143
+
144
+ ### Errors
145
+
146
+ `SendDartError` carries the `{statusCode, name, message}` envelope. Match on
147
+ `name` and read `status_code` — messages are scrubbed server-side and a few
148
+ handlers override the status a name usually maps to, so neither is safe to
149
+ hard-code. Extra fields ride along on the exception:
150
+
151
+ ```python
152
+ try:
153
+ senddart.Emails.send(params)
154
+ except senddart.SendDartError as e:
155
+ if e.name == "daily_quota_exceeded":
156
+ print(e.limit["used"], e.limit["limit"], e.limit["next_plan"])
157
+ if e.retry_after:
158
+ time.sleep(e.retry_after)
159
+ print(e.body) # the full parsed error body
160
+
161
+ try:
162
+ senddart.Batch.send(payloads, options={"idempotency_key": "batch-1"})
163
+ except senddart.SendDartError as e:
164
+ already_sent = e.sent # [{"id": ...}, ...] — do NOT resend these
165
+ print(e.sent_count)
166
+ ```
167
+
168
+ ## The domain-first model
169
+
170
+ SendDart is DOMAIN-FIRST: each of your verified sending domains has its own
171
+ contact pool — the same address on two domains is two records with separate
172
+ consent. That means:
173
+
174
+ - `Contacts` take a `domain` (required to create/list on the flat `/contacts`
175
+ API; disambiguates an email id on get/update/remove).
176
+ - `Segments` and `Topics` belong to a domain (`domain` required on create and list).
177
+ - `Campaigns.create` REQUIRES `domain` — it picks the contact pool the campaign
178
+ targets (the `from` address may be a different verified domain).
179
+ - `Automations.create` REQUIRES `domain`, and `Events.send` REQUIRES `domain` —
180
+ only automations belonging to that domain are triggered, so the same event
181
+ name (e.g. `user.created`) across several products can never double-fire.
182
+
183
+ ## Resources
184
+
185
+ Each resource is a class with methods following a consistent
186
+ `create` / `get` / `list` / `update` / `remove` shape (plus resource-specific verbs):
187
+ `Emails` (with nested `Emails.Receiving`), `Batch`,
188
+ `Domains`, `Audiences`, `Contacts`, `ContactProperties`, `Campaigns`,
189
+ `Segments`, `Topics`, `Templates`, `Automations`, `Webhooks`, `Events`,
190
+ `ApiKeys` (list only — see below), `Logs`, `Polls`.
191
+
192
+ ```python
193
+ # Emails
194
+ senddart.Emails.send(params)
195
+ senddart.Emails.list({"limit": 20, "after": cursor}) # cursor pagination
196
+ senddart.Emails.list({"status": "bounced", "search": "acme.com"}) # filters
197
+ senddart.Emails.list({"folder": "sent"}) # outbox / sent / scheduled / failed — any other value 422s
198
+ senddart.Emails.get(email_id)
199
+ senddart.Emails.update(email_id, {"scheduled_at": "2026-08-01T09:00:00Z"}) # reschedule
200
+ senddart.Emails.cancel(email_id)
201
+ senddart.Emails.sources() # per-campaign/automation send metrics
202
+ senddart.Emails.list_attachments(email_id)
203
+ senddart.Emails.get_attachment(email_id, attachment_id)
204
+
205
+ # Inbound email
206
+ senddart.Emails.Receiving.list()
207
+ senddart.Emails.Receiving.list_addresses() # per-address inbound stats
208
+ senddart.Emails.Receiving.get(email_id)
209
+ senddart.Emails.Receiving.list_attachments(email_id)
210
+ senddart.Emails.Receiving.get_attachment(email_id, attachment_id) # -> bytes
211
+ senddart.Emails.Receiving.get_raw(email_id) # -> bytes (RFC822)
212
+ senddart.Emails.Receiving.forward(email_id, {"from": "me@yourdomain.com", "to": "delivered@test.senddart.com"})
213
+ senddart.Emails.Receiving.reply(email_id, {"from": "me@yourdomain.com", "html": "<p>Thanks!</p>"})
214
+ senddart.Emails.Receiving.remove(email_id)
215
+
216
+ # Domains (incl. claiming a domain verified elsewhere + one-click DNS)
217
+ senddart.Domains.create({"name": "yourdomain.com"})
218
+ senddart.Domains.verify(domain_id)
219
+ senddart.Domains.claim({"name": "yourdomain.com"})
220
+ senddart.Domains.verify_claim(domain_id)
221
+ senddart.Domains.detect_dns(domain_id)
222
+ senddart.Domains.apply_cloudflare_dns(domain_id, {"token": cf_token})
223
+ senddart.Domains.mx_check("yourdomain.com") # live MX lookup
224
+ senddart.Domains.records_csv(domain_id) # -> bytes (text/csv)
225
+
226
+ # Contacts (domain-first)
227
+ senddart.Contacts.create({"domain": "yourdomain.com", "email": "user@example.com", "first_name": "Ada"})
228
+ senddart.Contacts.list({"domain": "yourdomain.com"})
229
+ senddart.Contacts.get({"id": contact_id}) # by id (exact) …
230
+ senddart.Contacts.get({"id": "user@example.com", "domain": "yourdomain.com"}) # … or by email + domain
231
+ senddart.Contacts.update({"id": contact_id, "unsubscribed": True})
232
+ senddart.Contacts.remove({"id": contact_id})
233
+ senddart.Contacts.batch({"audience_id": aud_id, "contacts": [{"email": "a@b.com"}]})
234
+ # Domain-first: import straight into a domain's pool, no audience id needed.
235
+ senddart.Contacts.batch({"domain": "yourdomain.com", "contacts": [{"email": "a@b.com"}]})
236
+ senddart.Contacts.import_csv({"audience_id": aud_id, "csv": "email,company\na@b.com,Acme"})
237
+ senddart.Contacts.create_import_upload({"audience_id": aud_id, "filename": "big.csv", "size": 90_000_000})
238
+ senddart.Contacts.add_to_segment(contact_id, segment_id)
239
+ senddart.Contacts.list_segments(contact_id)
240
+ senddart.Contacts.update_topics(contact_id, {"topics": [{"id": topic_id, "subscription": "opt_in"}]})
241
+
242
+ # Contact properties (custom fields / merge tags)
243
+ senddart.ContactProperties.create({"key": "plan", "type": "string"})
244
+
245
+ # Campaigns & Segments (domain-first)
246
+ senddart.Campaigns.create({"domain": "yourdomain.com", "from": sender, "subject": subject, "html": html})
247
+ senddart.Campaigns.send(campaign_id, {"scheduled_at": "tomorrow at 9am"})
248
+ senddart.Campaigns.stats(campaign_id)
249
+ senddart.Campaigns.engagement(campaign_id) # who opened / clicked / replied
250
+ senddart.Campaigns.ab(campaign_id)
251
+ senddart.Segments.create({"domain": "yourdomain.com", "name": "VIP", "filter": {"status": "subscribed"}})
252
+ senddart.Segments.list({"domain": "yourdomain.com"})
253
+ senddart.Segments.contacts(segment_id) # preview who matches
254
+
255
+ # Topics (domain-first)
256
+ senddart.Topics.create({"domain": "yourdomain.com", "name": "Product updates", "default_subscription": "opt_in"})
257
+ senddart.Topics.list({"domain": "yourdomain.com"})
258
+
259
+ # Templates
260
+ senddart.Templates.create({"name": "Welcome", "subject": "Hi {{first_name}}", "html": html})
261
+ senddart.Templates.duplicate(template_id)
262
+ senddart.Templates.publish(template_id)
263
+ senddart.Emails.send({"from": sender, "to": to, "template_id": tmpl_id, "variables": {"first_name": "Ada"}})
264
+
265
+ # Audiences
266
+ senddart.Audiences.list()
267
+ senddart.Audiences.import_sheet(audience_id, {"url": sheet_url})
268
+
269
+ # API keys (listing only — creating, re-scoping and revoking is dashboard-only)
270
+ senddart.ApiKeys.list()
271
+
272
+ # Logs & Polls
273
+ senddart.Logs.list({"limit": 100, "method": "POST", "status": 429})
274
+ senddart.Logs.get(log_id)
275
+ senddart.Polls.list()
276
+ senddart.Polls.get(email_id)
277
+ ```
278
+
279
+ ### API keys are managed in the dashboard
280
+
281
+ `ApiKeys.list()` is the whole surface: the SDK deliberately exposes no method to
282
+ create, re-scope or revoke a key. Key lifecycle belongs to a signed-in dashboard
283
+ session, and the API enforces it — `POST /api-keys`, `PATCH /api-keys/:id` and
284
+ `DELETE /api-keys/:id` answer `403 dashboard_only` to any API-key caller,
285
+ whatever its permission. That is the point: a key that leaks cannot mint itself
286
+ a replacement, widen its own access, or revoke the keys you would use to shut it
287
+ off. Create and revoke keys at
288
+ [senddart.com](https://www.senddart.com) instead.
289
+
290
+ ### Automations & Events
291
+
292
+ Every automation belongs to one of your sending domains — `domain` is required
293
+ on create, and `Events.send` names the domain it targets.
294
+
295
+ ```python
296
+ automation = senddart.Automations.create({
297
+ "name": "Welcome series",
298
+ "domain": "yourdomain.com",
299
+ "trigger": "contact.created",
300
+ })
301
+
302
+ senddart.Automations.add_step(automation["id"], {
303
+ "type": "send_email",
304
+ "config": {"template_id": "tmpl_welcome"},
305
+ })
306
+ senddart.Automations.update(automation["id"], {"status": "enabled"})
307
+
308
+ # Fire a custom event — only yourdomain.com's automations are triggered
309
+ senddart.Events.send({
310
+ "event": "signup.completed",
311
+ "domain": "yourdomain.com",
312
+ "email": "delivered@test.senddart.com",
313
+ "payload": {"plan": "pro"},
314
+ })
315
+ senddart.Events.create({"name": "signup.completed", "schema": {"plan": "string"}})
316
+ senddart.Events.update(event_id, {"schema": {"plan": "string", "seats": "number"}})
317
+
318
+ # Inspect execution
319
+ runs = senddart.Automations.runs(automation["id"], {"limit": 25, "status": "failed"})
320
+ senddart.Automations.get_run(automation["id"], runs["data"][0]["id"])
321
+ senddart.Automations.stop(automation["id"])
322
+ ```
323
+
324
+ The step graph is edited while the automation is **disabled** —
325
+ `add_step` / `update_step` / `delete_step` (and changing `domain`, `trigger` or
326
+ `connections`) all 422 on an enabled automation.
327
+ `Automations.create_with_ai` builds or extends the graph from a prompt:
328
+
329
+ ```python
330
+ senddart.Automations.create_with_ai(automation["id"], {"prompt": "Wait 2 days, then send the welcome email"})
331
+ ```
332
+
333
+ ### Webhooks
334
+
335
+ ```python
336
+ hook = senddart.Webhooks.create({
337
+ "endpoint": "https://yourapp.com/hooks/senddart", # must be https://
338
+ "events": ["email.delivered", "email.bounced", "email.unsubscribed"],
339
+ })
340
+ signing_secret = hook["signing_secret"] # shown ONCE, only here
341
+
342
+ senddart.Webhooks.list()
343
+ senddart.Webhooks.update(hook["id"], {"status": "disabled"})
344
+ senddart.Webhooks.rotate(hook["id"]) # new secret, returned once
345
+ senddart.Webhooks.test(hook["id"])
346
+ ```
347
+
348
+ Verify incoming deliveries locally (no HTTP request) — pass the EXACT raw
349
+ request body string, the `svix-*` headers, and your signing secret:
350
+
351
+ ```python
352
+ result = senddart.Webhooks.verify(raw_body, request.headers, signing_secret)
353
+ if not result["valid"]:
354
+ abort(401) # result["reason"] says why, e.g. 'no_match'
355
+ ```
356
+
357
+ ### Pagination
358
+
359
+ `list()` methods accept optional cursor pagination — `{"limit", "after", "before"}`.
360
+ `limit` is an integer 1–100 (default 20); `after` and `before` are item ids and
361
+ cannot be combined. Responses are `{"object": "list", "has_more": bool, "data": [...]}` —
362
+ there is no `total` and no `next_cursor`, so page forward with the last
363
+ `data[-1]["id"]`:
364
+
365
+ ```python
366
+ page = senddart.Campaigns.list({"limit": 25})
367
+ while page["has_more"]:
368
+ page = senddart.Campaigns.list({"limit": 25, "after": page["data"][-1]["id"]})
369
+ ```
370
+
371
+ Called with **no** pagination params, most list endpoints return the whole
372
+ collection up to a 1,000-item ceiling (`Campaigns`, `Contacts`, `Segments`,
373
+ `ContactProperties`, `Domains`, `ApiKeys`, `Topics`, `Polls`, and the nested
374
+ contact/segment/topic lists) — past that the response is truncated and
375
+ `has_more` is `True`, so keep paging rather than trusting one call to be
376
+ complete. `Audiences`, `Automations`, `Automations.runs`, `Templates`,
377
+ `Webhooks` and `Events` cap at 20 instead — pass `limit` explicitly when it
378
+ matters.
379
+ An unknown cursor is not an error: it returns an empty page with
380
+ `has_more: False`.
381
+
382
+ ### Idempotency
383
+
384
+ Pass an idempotency key to safely retry a send — replaying the same key returns
385
+ the original response instead of sending twice:
386
+
387
+ ```python
388
+ senddart.Emails.send(params, options={"idempotency_key": "order-123"})
389
+ senddart.Batch.send(payloads, options={"idempotency_key": "orders-2026-08-08"})
390
+ ```
391
+
392
+ - The key must be **1 to 255 characters** — measured after the server trims it,
393
+ so 255, not 256 (`senddart.IDEMPOTENCY_KEY_MAX_LENGTH`). The SDK sends the
394
+ key verbatim and lets the **server** be the authority: an out-of-range key
395
+ comes back as a `SendDartError` with `name == "invalid_idempotency_key"`
396
+ (400).
397
+ - **`Emails.send`, `Batch.send`, and received-email reply/forward honour it.** Every other endpoint —
398
+ including `Events.send` — accepts and forwards the header but the API ignores
399
+ it, so a retry there creates a second resource. De-duplicate on your side
400
+ instead.
401
+ - Reusing a key with a *different* body raises `invalid_idempotent_request`
402
+ (409); reusing it while the first request is still running raises
403
+ `concurrent_idempotent_requests` (409).
404
+
405
+ ## Documentation
406
+
407
+ Full docs: <https://www.senddart.com/docs>
408
+
409
+ ## License
410
+
411
+ MIT
412
+
413
+ ## Recovery and tracking contracts
414
+
415
+ Use a stable, unique operation key for each intended send, batch, reply, or
416
+ forward. Keep the same key and payload when recovering that operation. These
417
+ are the supported idempotent send endpoints; events do not implement this
418
+ header. Existing calls without options still work.
419
+
420
+ ```python
421
+ senddart.Emails.Receiving.reply(email_id, reply, {"idempotency_key": "reply-operation-1"})
422
+ senddart.Emails.Receiving.forward(email_id, forward, {"idempotency_key": "forward-operation-1"})
423
+ health = senddart.Domains.tracking_health(domain_id)
424
+ ```
425
+
426
+ Automatic retries consider only 429/503. They stop on an original email `id`,
427
+ positive `sent_count`, nonempty `sent` or `reserved`, or `batch_incomplete`.
428
+ An ordinary rate limit can retry; a generic 503 can retry a read or a send with
429
+ the same supported key. Other writes retry only documented pre-processing
430
+ rejections (`service_unavailable`, `sending_service_unavailable`,
431
+ `sending_configuration_unavailable`, `contacts_busy`, `contacts_timeout`).
432
+ No network/body-read failure, 409, 422, or other 5xx is retried automatically.
433
+ The default transport refuses redirects; a custom transport/client must enforce
434
+ its own policy.
435
+
436
+ On a failed or unconfirmed send, inspect `id` with the email retrieval method
437
+ before creating another send. A 422 with an ID can identify an uncertain
438
+ provider handoff; 422 does not always mean nothing happened. For interrupted
439
+ batches, `sent` contains confirmed sends, `reserved` contains the original
440
+ attempted prefix (including uncertain handoffs), and `unsent_count` counts the
441
+ never-attempted tail. Do not resend the full batch or the reserved prefix under
442
+ a new key. Reconcile original IDs first, then submit only known unattempted
443
+ items as a new operation. Recovery fields remain available in the full error
444
+ body as well as language-specific fields/accessors.
445
+
446
+ Tracking health returns `custom_host`, `status` (`shared`, `ready`, or
447
+ `unavailable`), and `checked_at`. Configure custom tracking through the domain
448
+ API and check health before relying on it. A healthy endpoint cannot guarantee
449
+ an open event: recipients may block images, and coupon redemption alone is not
450
+ proof that the tracking pixel loaded. SDKs preserve supplied HTML/text and do
451
+ not infer opens or rewrite editor spacing.
452
+
453
+ Campaign cancellation also stops pending follow-ups for an already-sent
454
+ campaign while retaining its sent history. Permanent received-email deletion
455
+ acknowledges a durable cleanup request; attachment/object cleanup can finish
456
+ asynchronously. Retrying that deletion is safe; it cannot be undone after the
457
+ purge request is accepted.