senddart 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 283eab8c1be47c578fa465596d35ff85abf8b3c504ef041d21a3fbb23631697f
+  data.tar.gz: ae074cff46085c39c5d9b801c1324e5259a6e172f49ddd40bbb2516cea99fcd1
+SHA512:
+  metadata.gz: 4b4ab1becf2e4a760d96883384adf46743c3e8e19346f35858c0edc5cc46a7690635c538651bb932d0ee5d192a5224ef019e561a8154376b710b1d65dbe9da55
+  data.tar.gz: d5db56168fcad952b541148cf9c944463e6092735f267189ab860383ea0f6abe5a13eeded4ecfbd47d7e62ac685923c4f985aa23ce9b933418d614569577a795

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SendDart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,469 @@
+# senddart
+
+Official Ruby SDK for the [SendDart](https://www.senddart.com) email API — send transactional and marketing email from your own verified domain.
+
+Zero runtime dependencies: the gem uses only Ruby's standard library (`Net::HTTP`, `JSON`, `OpenSSL`).
+
+## Install
+
+```bash
+gem install senddart
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "senddart"
+```
+
+## Setup
+
+```ruby
+require "senddart"
+
+SendDart.api_key = "mb_xxxxxxxxx"
+
+# or
+SendDart.configure do |config|
+  config.api_key = ENV["SENDDART_API_KEY"]
+  # config.base_url = "https://www.senddart.com/api" # override your API host
+end
+```
+
+## Usage
+
+```ruby
+sent = SendDart::Emails.send({
+  from: "Acme <hello@yourdomain.com>",
+  to: ["delivered@test.senddart.com"], # the mailbox simulator (see below)
+  subject: "Hello from SendDart",
+  html: "<p>Your first email 🎉</p>"
+})
+puts sent["id"]
+```
+
+`delivered@test.senddart.com` is SendDart's mailbox simulator: the send is accepted, produces a real email object and a delivery event, and never reaches a provider. `bounced@`, `complained@` and `suppressed@test.senddart.com` exercise the other outcomes, and `delivered@` / `bounced@` / `complained@` accept a `+label` suffix (`delivered+signup@test.senddart.com`). Do **not** point a send at `example.com`, `example.net`, `example.org`, or an address under `.test`, `.invalid`, `.localhost` or `.example`: those are reserved for documentation, so every recipient is suppressed and the call comes back 422 `validation_error` ("All `to` recipients are suppressed") having sent nothing. They are fine as *contact* records — only the send path rejects them.
+
+Params are plain hashes with snake_case keys, passed through as JSON. Successful calls return the parsed response (a Hash, or a raw String for binary downloads). Any non-2xx response raises `SendDart::Error`:
+
+```ruby
+begin
+  SendDart::Emails.send(params)
+rescue SendDart::Error => e
+  puts e.status_code # => 422
+  puts e.name        # => "validation_error"
+  puts e.message     # => human-readable explanation
+end
+```
+
+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).
+
+Some errors carry more than that envelope. The extras are readers on the error and are `nil` on an ordinary one:
+
+```ruby
+rescue SendDart::Error => e
+  # WHICH quota ran out, and what would clear it.
+  if (cap = e.limit)
+    cap["kind"]                    # => "emails_daily"
+    cap["used"], cap["limit"]      # => 100, 100
+    cap["period"]                  # => "24h"
+    cap.dig("next_plan", "name")   # => "Pro"
+  end
+
+  # Reputation gates: whether waiting helps, and until when.
+  if (rep = e.reputation)
+    rep["retryable"], rep["scope"], rep["retry_at"]
+  end
+
+  # A batch that failed part way through — do NOT resend these.
+  if (sent = e.sent)
+    puts "#{e.sent_count} already went out: #{sent.map { |s| s['id'] }.join(', ')}"
+  end
+end
+```
+
+`e.body` is the whole parsed error body, so a field newer than this SDK version is still reachable.
+
+Every request carries a `User-Agent` automatically — the API rejects requests without one with a 403 `validation_error`.
+
+## Domain-first model
+
+SendDart is **domain-first**: each sending domain has its own pool of contacts. The same email address on two domains is two records with separate consent, so unsubscribes on one product never leak into another.
+
+That means `domain` (the sending domain, e.g. `"yourdomain.com"` — one of your verified domains) is **required** on:
+
+- `Contacts.create` / `Contacts.list` (the flat `/contacts` API — pass `audience_id:` to use the nested audience routes instead)
+- `Segments.create` / `Segments.list`
+- `Topics.create` / `Topics.list`
+- `Campaigns.create` (picks the contact pool the campaign targets; `from` may be a different verified domain)
+- `Automations.create` and `Events.send` (only automations belonging to that domain are triggered)
+
+## Emails
+
+```ruby
+SendDart::Emails.send({ from: from, to: to, subject: subject, html: html })
+SendDart::Emails.list({ limit: 20, after: cursor })   # cursor pagination
+SendDart::Emails.list({ status: "bounced", search: "acme.com" }) # filters
+SendDart::Emails.list({ folder: "scheduled" }) # one of outbox | sent | scheduled | failed — any other value is rejected (422)
+SendDart::Emails.sources                              # per-campaign/automation send metrics
+SendDart::Emails.get(email_id)
+SendDart::Emails.list_attachments(email_id)
+SendDart::Emails.get_attachment(email_id, attachment_id)
+SendDart::Emails.update(email_id, { scheduled_at: "2026-08-01T09:00:00Z" }) # reschedule
+SendDart::Emails.cancel(email_id)
+
+# Batch send — up to 100 emails in one request.
+# Batch items reject `attachments` and `scheduled_at` (422) — send those individually.
+SendDart::Batch.send([
+  { from: from, to: ["delivered+a@test.senddart.com"], subject: "Hi A", html: "<p>A</p>" },
+  { from: from, to: ["delivered+b@test.senddart.com"], subject: "Hi B", html: "<p>B</p>" }
+])
+
+# Attachments: hosted URL (path) or inline base64 (content)
+SendDart::Emails.send({
+  from: from, to: to, subject: "Your invoice", html: "<p>Attached.</p>",
+  attachments: [
+    { filename: "invoice.pdf", path: "https://yourdomain.com/invoices/invoice.pdf" },
+    { filename: "report.csv", content: base64_content, content_type: "text/csv" }
+  ]
+})
+```
+
+### Inbound email
+
+```ruby
+SendDart::Emails::Receiving.list
+SendDart::Emails::Receiving.list_addresses # per-address inbound stats
+SendDart::Emails::Receiving.get(id)
+SendDart::Emails::Receiving.list_attachments(id)
+SendDart::Emails::Receiving.get_attachment(id, attachment_id) # => raw bytes (String)
+SendDart::Emails::Receiving.get_raw(id)                           # => original RFC822 message
+SendDart::Emails::Receiving.forward(id, { from: "you@yourdomain.com", to: "team@you.com" })
+SendDart::Emails::Receiving.reply(id, { from: "you@yourdomain.com", html: "<p>Thanks!</p>" })
+SendDart::Emails::Receiving.delete(id)
+```
+
+## Domains
+
+```ruby
+SendDart::Domains.create({ name: "yourdomain.com" })
+SendDart::Domains.get(id)
+SendDart::Domains.list
+SendDart::Domains.update(id, { click_tracking: true })
+SendDart::Domains.verify(id)
+SendDart::Domains.mx_check("yourdomain.com") # inspect live MX before enabling receiving
+SendDart::Domains.records_csv(id)            # => CSV text (String)
+SendDart::Domains.delete(id)
+
+# Claim a domain verified in another account
+SendDart::Domains.claim({ name: "yourdomain.com" })
+SendDart::Domains.get_claim(id)
+SendDart::Domains.verify_claim(id)
+
+# One-click DNS setup
+SendDart::Domains.detect_dns(id)
+SendDart::Domains.apply_cloudflare_dns(id, { token: cf_token })
+SendDart::Domains.apply_godaddy_dns(id, { key: key, secret: secret })
+SendDart::Domains.apply_namecheap_dns(id, { apiUser: user, apiKey: key })
+```
+
+## Contacts (domain-first)
+
+```ruby
+SendDart::Contacts.create({ domain: "yourdomain.com", email: "user@example.com", first_name: "Ada" })
+SendDart::Contacts.list({ domain: "yourdomain.com" })
+SendDart::Contacts.get({ id: contact_id })                                # by id (exact) …
+SendDart::Contacts.get({ id: "user@example.com", domain: "yourdomain.com" }) # … or email + domain
+SendDart::Contacts.update({ id: contact_id, unsubscribed: true })
+SendDart::Contacts.delete({ id: contact_id })
+
+# Nested audience variants
+SendDart::Contacts.create({ audience_id: aud_id, email: "user@example.com" })
+SendDart::Contacts.list({ audience_id: aud_id, segment_id: seg_id })
+
+# Bulk import
+SendDart::Contacts.batch({ audience_id: aud_id, contacts: [{ email: "a@b.com" }], on_conflict: "skip" })
+# Domain-first: import straight into a domain's pool, no audience id needed.
+SendDart::Contacts.batch({ domain: "yourdomain.com", contacts: [{ email: "a@b.com" }] })
+SendDart::Contacts.import({ audience_id: aud_id, csv: "email,company\na@b.com,Acme" })
+
+# CSV too big to inline (5 MB / 10,000 rows)? Upload it directly, then import by key.
+slot = SendDart::Contacts.create_import_upload({ audience_id: aud_id, filename: "list.csv", size: bytes })
+# PUT the file to slot["upload_url"], then:
+SendDart::Contacts.import({ audience_id: aud_id, storage_key: slot["storage_key"] })
+
+# Segments & topics per contact
+SendDart::Contacts.add_to_segment(contact_id, segment_id)
+SendDart::Contacts.remove_from_segment(contact_id, segment_id)
+SendDart::Contacts.list_segments(contact_id)
+SendDart::Contacts.get_topics(contact_id)
+SendDart::Contacts.update_topics(contact_id, { topics: [{ id: topic_id, subscription: "opt_in" }] })
+
+# Custom contact properties ({{merge_tags}})
+SendDart::ContactProperties.create({ key: "plan", type: "string", fallback_value: "free" })
+```
+
+## Audiences
+
+```ruby
+SendDart::Audiences.create({ name: "Newsletter" })
+SendDart::Audiences.get(id)
+SendDart::Audiences.list
+SendDart::Audiences.update(id, { name: "Weekly newsletter" })
+SendDart::Audiences.delete(id)
+
+# Import from a link-shared Google Sheet
+SendDart::Audiences.import_sheet(id, { url: sheet_url, segment_name: "June leads" })
+```
+
+## Segments & Topics (domain-first)
+
+```ruby
+SendDart::Segments.create({ domain: "yourdomain.com", name: "VIP", filter: { status: "subscribed" } })
+SendDart::Segments.list({ domain: "yourdomain.com" })
+SendDart::Segments.get(id)
+SendDart::Segments.contacts(id) # preview who matches
+SendDart::Segments.update(id, { name: "VIP customers" })
+SendDart::Segments.delete(id)
+
+SendDart::Topics.create({ domain: "yourdomain.com", name: "Product updates", default_subscription: "opt_in" })
+SendDart::Topics.list({ domain: "yourdomain.com" })
+SendDart::Topics.update(id, { description: "New features" })
+SendDart::Topics.delete(id)
+```
+
+## Campaigns (domain-first)
+
+```ruby
+campaign = SendDart::Campaigns.create({
+  domain: "yourdomain.com", # REQUIRED — the contact pool this campaign targets
+  from: "Acme <hello@yourdomain.com>",
+  subject: "Big news",
+  html: "<p>Hello {{first_name}}</p>",
+  segment_id: seg_id # optional — subset instead of everyone
+})
+
+SendDart::Campaigns.send(campaign["id"])                                    # send now
+SendDart::Campaigns.send(campaign["id"], { scheduled_at: "2026-08-01T09:00:00Z" }) # or schedule
+SendDart::Campaigns.cancel(campaign["id"])
+SendDart::Campaigns.stats(campaign["id"])
+SendDart::Campaigns.engagement(campaign["id"]) # who opened / clicked / replied
+SendDart::Campaigns.ab(campaign["id"]) # A/B winner evaluation
+SendDart::Campaigns.get(campaign["id"])
+SendDart::Campaigns.list({ limit: 25 })
+SendDart::Campaigns.update(campaign["id"], { subject: "Bigger news" })
+SendDart::Campaigns.delete(campaign["id"])
+```
+
+## Templates
+
+```ruby
+tmpl = SendDart::Templates.create({ name: "Welcome", subject: "Welcome!", html: "<p>Hi {{first_name}}</p>" })
+SendDart::Templates.publish(tmpl["id"])
+SendDart::Templates.duplicate(tmpl["id"], { name: "Welcome v2" })
+SendDart::Templates.get(tmpl["id"])
+SendDart::Templates.list
+SendDart::Templates.update(tmpl["id"], { subject: "Welcome aboard!" })
+SendDart::Templates.delete(tmpl["id"])
+
+# Send with a template
+SendDart::Emails.send({ from: from, to: to, template_id: tmpl["id"], variables: { first_name: "Ada" } })
+```
+
+## Automations & Events (domain-first)
+
+```ruby
+automation = SendDart::Automations.create({
+  name: "Welcome series",
+  domain: "yourdomain.com", # REQUIRED
+  trigger: "contact.created"
+})
+
+SendDart::Automations.add_step(automation["id"], { type: "send_email", config: { template_id: tmpl_id } })
+# `type` is REQUIRED on update_step: PATCH re-validates the whole step and
+# `config` REPLACES the stored config wholesale (there is no merge), so resend
+# every key you want to keep. A step's graph `key` is create-only — settable on
+# add_step, ignored here — so delete and re-add a step to re-key it.
+SendDart::Automations.update_step(automation["id"], step_id, { type: "send_email", config: { template_id: tmpl_id, subject: "New subject" } })
+SendDart::Automations.update(automation["id"], { status: "enabled" })
+
+# Or describe the flow and let the server build the steps (automation must be stopped)
+SendDart::Automations.create_with_ai(automation["id"], { prompt: "Wait 2 days, then send the onboarding email" })
+
+# Fire a custom event — only yourdomain.com's automations are triggered
+SendDart::Events.send({
+  event: "signup.completed",
+  domain: "yourdomain.com", # REQUIRED
+  email: "user@example.com",
+  payload: { plan: "pro" }
+})
+
+# Event definitions — schema types are "string", "number", "boolean" or "date".
+# Event names cannot start with the reserved "senddart:" prefix.
+SendDart::Events.create({ name: "signup.completed", schema: { plan: "string" } })
+SendDart::Events.list
+SendDart::Events.update(event_id, { schema: { plan: "string", seats: "number" } }) # name is immutable
+SendDart::Events.delete(event_id)
+
+# Inspect execution
+runs = SendDart::Automations.runs(automation["id"], { limit: 25, status: ["failed"] })
+SendDart::Automations.get_run(automation["id"], runs["data"].first["id"])
+SendDart::Automations.delete_step(automation["id"], step_id)
+SendDart::Automations.stop(automation["id"])
+SendDart::Automations.delete(automation["id"])
+```
+
+## Webhooks
+
+```ruby
+hook = SendDart::Webhooks.create({
+  endpoint: "https://yourapp.com/hooks/senddart",
+  events: ["email.delivered", "email.bounced", "email.unsubscribed"]
+})
+hook["signing_secret"] # shown ONCE — store it
+
+SendDart::Webhooks.list
+SendDart::Webhooks.update(hook["id"], { status: "disabled" })
+SendDart::Webhooks.rotate(hook["id"]) # new secret returned once
+SendDart::Webhooks.test(hook["id"])
+SendDart::Webhooks.delete(hook["id"])
+```
+
+Endpoints must be `https://` and must not resolve to a private address. Valid event names are `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.failed`, `email.scheduled`, `email.suppressed`, `email.received`, `email.replied`, `email.unsubscribed`, `contact.created`, `contact.updated`, `contact.deleted`, `domain.created`, `domain.updated` and `domain.deleted`. Anything else is a 422.
+
+`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"`):
+
+```ruby
+result = SendDart::Webhooks.test(hook["id"])
+warn "test delivery failed: #{result['error']}" unless result["ok"]
+```
+
+### Verifying deliveries
+
+`verify` checks the Svix-style HMAC-SHA256 signature locally (no HTTP request). Pass the **exact raw request body** — re-serializing parsed JSON breaks the signature.
+
+```ruby
+result = SendDart::Webhooks.verify(
+  request.raw_post,          # raw body string
+  {
+    "svix-id" => request.headers["svix-id"],
+    "svix-timestamp" => request.headers["svix-timestamp"],
+    "svix-signature" => request.headers["svix-signature"]
+  },
+  signing_secret             # the whsec_... secret from create/rotate
+)
+
+head :unauthorized unless result[:valid]
+# result => { valid: true } or { valid: false, reason: "no_match" | "timestamp_out_of_tolerance" | ... }
+```
+
+Pass `tolerance: 0` to skip the timestamp freshness check (default 300 seconds).
+
+## API keys, Logs & Polls
+
+```ruby
+SendDart::ApiKeys.list # `token` is the 8-character display prefix, never the secret
+
+SendDart::Logs.list({ limit: 100, method: "POST", status: 429 })
+SendDart::Logs.get(log_id)
+
+SendDart::Polls.list
+SendDart::Polls.get(email_id) # aggregated answer breakdown
+```
+
+`SendDart::ApiKeys.list` is the whole API-key surface: the SDK deliberately
+exposes no method to create, re-scope or revoke a key. Key lifecycle belongs to
+a signed-in dashboard session, and the API enforces it — `POST /api-keys`,
+`PATCH /api-keys/:id` and `DELETE /api-keys/:id` answer `403 dashboard_only` to
+any API-key caller, whatever its permission. That is the point: a key that leaks
+cannot mint itself a replacement, widen its own access, or revoke the keys you
+would use to shut it off. Create and revoke keys at
+[senddart.com](https://www.senddart.com).
+
+## Pagination
+
+`list` methods accept cursor pagination — `{ limit:, after:, before: }` — appended as a query string:
+
+```ruby
+page = SendDart::Campaigns.list({ limit: 25, after: "cursor_abc" })
+page["object"]   # => "list"
+page["has_more"] # => true when more rows exist beyond this page
+page["data"]     # => [...]
+```
+
+`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`.
+
+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.
+
+## Idempotency
+
+Pass an idempotency key to safely retry a send.
+
+```ruby
+SendDart::Emails.send(payload, { idempotency_key: "order-123" })
+SendDart::Batch.send(payloads, { idempotency_key: "orders-2026-08-08" })
+```
+
+The key must be **1–255 characters**, measured after the server trims it — 255, not 256. `SendDart::Client::IDEMPOTENCY_KEY_MAX_LENGTH` carries that number. The SDK sends the key verbatim and lets the **server** be the authority: an out-of-range key comes back as `400 invalid_idempotency_key` (a `SendDart::Error` with `name == "invalid_idempotency_key"`).
+
+Reusing a key replays the original response; reusing it with a *different* body is a 409 (`invalid_idempotent_request`), and a second request while the first is still in flight is a 409 (`concurrent_idempotent_requests`).
+
+`Emails.send`, `Batch.send`, and received-email reply/forward honour the header. Every other endpoint — including `Events.send` — accepts and forwards it but the API ignores it, so a retry there creates a second record. De-duplicate on your side instead.
+
+## Rate limits
+
+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`.
+
+## Documentation
+
+Full docs: <https://www.senddart.com/docs>
+
+## License
+
+MIT
+
+## Recovery and tracking contracts
+
+Use a stable, unique operation key for each intended send, batch, reply, or
+forward. Keep the same key and payload when recovering that operation. These
+are the supported idempotent send endpoints; events do not implement this
+header. Existing calls without options still work.
+
+```ruby
+SendDart::Emails::Receiving.reply(id, reply, idempotency_key: "reply-operation-1")
+SendDart::Emails::Receiving.forward(id, forward, idempotency_key: "forward-operation-1")
+health = SendDart::Domains.tracking_health(domain_id)
+```
+
+Automatic retries consider only 429/503. They stop on an original email `id`,
+positive `sent_count`, nonempty `sent` or `reserved`, or `batch_incomplete`.
+An ordinary rate limit can retry; a generic 503 can retry a read or a send with
+the same supported key. Other writes retry only documented pre-processing
+rejections (`service_unavailable`, `sending_service_unavailable`,
+`sending_configuration_unavailable`, `contacts_busy`, `contacts_timeout`).
+No network/body-read failure, 409, 422, or other 5xx is retried automatically.
+The default transport refuses redirects; a custom transport/client must enforce
+its own policy.
+
+On a failed or unconfirmed send, inspect `id` with the email retrieval method
+before creating another send. A 422 with an ID can identify an uncertain
+provider handoff; 422 does not always mean nothing happened. For interrupted
+batches, `sent` contains confirmed sends, `reserved` contains the original
+attempted prefix (including uncertain handoffs), and `unsent_count` counts the
+never-attempted tail. Do not resend the full batch or the reserved prefix under
+a new key. Reconcile original IDs first, then submit only known unattempted
+items as a new operation. Recovery fields remain available in the full error
+body as well as language-specific fields/accessors.
+
+Tracking health returns `custom_host`, `status` (`shared`, `ready`, or
+`unavailable`), and `checked_at`. Configure custom tracking through the domain
+API and check health before relying on it. A healthy endpoint cannot guarantee
+an open event: recipients may block images, and coupon redemption alone is not
+proof that the tracking pixel loaded. SDKs preserve supplied HTML/text and do
+not infer opens or rewrite editor spacing.
+
+Campaign cancellation also stops pending follow-ups for an already-sent
+campaign while retaining its sent history. Permanent received-email deletion
+acknowledges a durable cleanup request; attachment/object cleanup can finish
+asynchronously. Retrying that deletion is safe; it cannot be undone after the
+purge request is accepted.

data/lib/senddart/api_keys.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SendDart
+  # Listing only, by design. Keys are created, re-scoped and revoked in the
+  # SendDart dashboard by a signed-in user — POST /api-keys,
+  # PATCH /api-keys/:id and DELETE /api-keys/:id answer 403 `dashboard_only`
+  # to every API-key caller, whatever its permission. Exposing only `list`
+  # means a leaked key cannot mint itself a replacement or widen its access.
+  module ApiKeys
+    class << self
+      # GET /api-keys — with no pagination params one page carries up to 1,000
+      # non-revoked keys and `has_more` reports any truncation. `token` here is
+      # the 8-character display prefix, never the secret.
+      def list(params = {})
+        Client.request(:get, "/api-keys", query: Client.pagination(params))
+      end
+    end
+  end
+end

data/lib/senddart/audiences.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SendDart
+  module Audiences
+    class << self
+      # POST /audiences — params: { name: "..." }
+      def create(params)
+        Client.request(:post, "/audiences", body: params)
+      end
+
+      # GET /audiences/:id
+      def get(audience_id)
+        Client.request(:get, "/audiences/#{Client.path_escape(audience_id)}")
+      end
+
+      # GET /audiences
+      def list(params = {})
+        Client.request(:get, "/audiences", query: Client.pagination(params))
+      end
+
+      # Rename an audience. PATCH /audiences/:id
+      def update(audience_id, params)
+        Client.request(:patch, "/audiences/#{Client.path_escape(audience_id)}", body: params)
+      end
+
+      # DELETE /audiences/:id
+      def delete(audience_id)
+        Client.request(:delete, "/audiences/#{Client.path_escape(audience_id)}")
+      end
+
+      # Import contacts from a link-shared Google Sheet; header columns become
+      # contact properties and rows land in a fresh segment.
+      # POST /audiences/:id/contacts/import-sheet — params: { url:, segment_name: }
+      def import_sheet(audience_id, params)
+        Client.request(:post, "/audiences/#{Client.path_escape(audience_id)}/contacts/import-sheet", body: params)
+      end
+    end
+  end
+end

data/lib/senddart/automations.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module SendDart
+  # Automations are DOMAIN-FIRST: `domain` is required on create, and only
+  # Events.send calls naming the same domain trigger them.
+  module Automations
+    class << self
+      # POST /automations
+      #   SendDart::Automations.create({ name: "Welcome series", domain: "yourdomain.com",
+      #                                    trigger: "contact.created" })
+      # The built-in "senddart:schedule" trigger fires once at
+      # `trigger_config` ({ at: ISO 8601 instant, timezone: IANA name }),
+      # enrolling every contact of the domain's pool — `trigger_config` is
+      # required with that trigger and not accepted on any other.
+      def create(params)
+        Client.require_domain!(params, "Automations.create")
+        Client.request(:post, "/automations", body: params)
+      end
+
+      # GET /automations/:id
+      def get(automation_id)
+        Client.request(:get, "/automations/#{Client.path_escape(automation_id)}")
+      end
+
+      # GET /automations
+      def list(params = {})
+        Client.request(:get, "/automations", query: Client.pagination(params))
+      end
+
+      # PATCH /automations/:id — params: { name:, status: "enabled"|"disabled", ... }
+      # `trigger_config` ({ at:, timezone: }) updates the "senddart:schedule"
+      # trigger's schedule (only valid on automations with that trigger).
+      def update(automation_id, params)
+        Client.request(:patch, "/automations/#{Client.path_escape(automation_id)}", body: params)
+      end
+
+      # Append a step. POST /automations/:id/steps — params: { type:, config:, key: }
+      # The automation must be disabled first, and `type: "trigger"` is
+      # rejected here (the trigger lives on the automation, not in `steps`).
+      def add_step(automation_id, params)
+        Client.request(:post, "/automations/#{Client.path_escape(automation_id)}/steps", body: params)
+      end
+
+      # Edit a step in place (automation must be disabled).
+      # PATCH /automations/:id/steps/:step_id — params: { type:, config: }
+      # `type` is REQUIRED: the server re-validates the whole step, so omitting
+      # it is a validation_error naming the valid types. `config` REPLACES the
+      # stored config wholesale (there is no merge) — resend every key you want
+      # to keep. `key` is not accepted here; a step's graph key is create-only
+      # (set on add_step), so delete and re-add a step to re-key it.
+      def update_step(automation_id, step_id, params)
+        Client.request(
+          :patch,
+          "/automations/#{Client.path_escape(automation_id)}/steps/#{Client.path_escape(step_id)}",
+          body: params
+        )
+      end
+
+      # Delete a step. DELETE /automations/:id/steps/:step_id
+      def delete_step(automation_id, step_id)
+        Client.request(:delete, "/automations/#{Client.path_escape(automation_id)}/steps/#{Client.path_escape(step_id)}")
+      end
+
+      # Build (or extend) the automation's steps from a prompt.
+      # POST /automations/:id/ai — params: { prompt:, template_ids:, events:, attach: }
+      # `prompt` is required and capped at 2000 characters. Without `attach` the
+      # automation must have no steps yet; pass `attach` ({ from:, type:,
+      # before: }) to append to an existing graph. The automation must be
+      # stopped, and the route is limited to 20 requests per minute per account.
+      def create_with_ai(automation_id, params)
+        Client.request(:post, "/automations/#{Client.path_escape(automation_id)}/ai", body: params)
+      end
+
+      # List an automation's runs. `status` filters to specific run statuses
+      # ("running", "completed", "failed", "skipped") and accepts an Array or a
+      # comma-separated String. GET /automations/:id/runs
+      def runs(automation_id, params = {})
+        query = Client.pagination(params)
+        status = Client.opt(params, :status)
+        query[:status] = status.is_a?(Array) ? status.join(",") : status unless status.nil?
+        Client.request(:get, "/automations/#{Client.path_escape(automation_id)}/runs", query: query)
+      end
+
+      # Retrieve a single run with its step trace. GET /automations/:id/runs/:run_id
+      def get_run(automation_id, run_id)
+        Client.request(:get, "/automations/#{Client.path_escape(automation_id)}/runs/#{Client.path_escape(run_id)}")
+      end
+
+      # Stop an automation — no new runs; in-progress runs finish. POST /automations/:id/stop
+      def stop(automation_id)
+        Client.request(:post, "/automations/#{Client.path_escape(automation_id)}/stop")
+      end
+
+      # DELETE /automations/:id
+      def delete(automation_id)
+        Client.request(:delete, "/automations/#{Client.path_escape(automation_id)}")
+      end
+    end
+  end
+end