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.
- senddart-1.0.0/LICENSE +21 -0
- senddart-1.0.0/MANIFEST.in +1 -0
- senddart-1.0.0/PKG-INFO +457 -0
- senddart-1.0.0/README.md +430 -0
- senddart-1.0.0/pyproject.toml +35 -0
- senddart-1.0.0/senddart/__init__.py +80 -0
- senddart-1.0.0/senddart/api_keys.py +21 -0
- senddart-1.0.0/senddart/audiences.py +56 -0
- senddart-1.0.0/senddart/automations.py +175 -0
- senddart-1.0.0/senddart/batch.py +40 -0
- senddart-1.0.0/senddart/campaigns.py +128 -0
- senddart-1.0.0/senddart/contact_properties.py +50 -0
- senddart-1.0.0/senddart/contacts.py +256 -0
- senddart-1.0.0/senddart/domains.py +140 -0
- senddart-1.0.0/senddart/emails.py +296 -0
- senddart-1.0.0/senddart/events.py +75 -0
- senddart-1.0.0/senddart/exceptions.py +109 -0
- senddart-1.0.0/senddart/http_client.py +295 -0
- senddart-1.0.0/senddart/logs.py +41 -0
- senddart-1.0.0/senddart/polls.py +18 -0
- senddart-1.0.0/senddart/segments.py +86 -0
- senddart-1.0.0/senddart/templates.py +89 -0
- senddart-1.0.0/senddart/topics.py +71 -0
- senddart-1.0.0/senddart/webhooks.py +292 -0
- senddart-1.0.0/senddart.egg-info/PKG-INFO +457 -0
- senddart-1.0.0/senddart.egg-info/SOURCES.txt +39 -0
- senddart-1.0.0/senddart.egg-info/dependency_links.txt +1 -0
- senddart-1.0.0/senddart.egg-info/top_level.txt +1 -0
- senddart-1.0.0/setup.cfg +4 -0
- senddart-1.0.0/tests/__init__.py +0 -0
- senddart-1.0.0/tests/fixtures/http-recovery-corpus.json +19 -0
- senddart-1.0.0/tests/helpers.py +50 -0
- senddart-1.0.0/tests/test_campaigns.py +58 -0
- senddart-1.0.0/tests/test_contacts.py +162 -0
- senddart-1.0.0/tests/test_domains.py +59 -0
- senddart-1.0.0/tests/test_emails.py +139 -0
- senddart-1.0.0/tests/test_http_client.py +447 -0
- senddart-1.0.0/tests/test_misc_resources.py +183 -0
- senddart-1.0.0/tests/test_recovery.py +105 -0
- senddart-1.0.0/tests/test_segments.py +57 -0
- 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
|
senddart-1.0.0/PKG-INFO
ADDED
|
@@ -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.
|