mailtea 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98e959c77cb6dc2c7b99cff06807b2c18052d6147bd03ec4b8256f89c88859e9
-  data.tar.gz: 814086291d3c3937eb1cadeae73500add856b67f4f28ea1105a3ddceb4fceb9b
+  metadata.gz: d690859b9a966c7c3446b88a8ad18eaa3c403af32137d7e15e8aab72294cd79e
+  data.tar.gz: 9227bf62c989dce0a000d90433eb769d2762ba515614bbe037bb1b2cfbc4d0df
 SHA512:
-  metadata.gz: b0cc04ddef836710cfc8690c8c4fee4fc400e04603be449d491024eaeac2a5c3b4558d31fd32bd8e509d4ec7e5c07cc1f48160d75b995fb45fca7514c217e807
-  data.tar.gz: 2fa9199a5dded8c0b80024fe49fe54d82c1bb037cf96fe15d02f4c4ff20ed6d7e2b1064a167c1eaf83c9d83fce065e1e0c047e7602977ec9eff15029df1dac83
+  metadata.gz: 407fd01f8e7850bb13e4042955f4bdde236190f61a431718d3a76276218e92564bb1ee882bbbaca096c0239b72f60e1b4eb986c7b18111827a2822e1a3b75e1e
+  data.tar.gz: 5fb8f59e24537373bb3756257954c859cef61043cc3dd54478fe15720a53d77002a01898ba8867891d28454c7f8fa01620cbbf415209c667f80ea7d9b1c9a92e

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to the `mailtea` Ruby gem are documented here.
 
+## 0.4.0 (2026-09-15)
+
+- Added: test mode. `mailtea.api_keys.create(name: "CI", mode: "test")` mints a
+  test key (prefixed `mt_test_`) whose sends are validated, recorded and
+  webhook-emitting but never delivered, so CI can run against production Mailtea
+  with your real code and your real webhook handler. A test key is **not** a
+  data sandbox — it reads and writes your real contacts, templates, senders and
+  webhooks. Only delivery is simulated.
+- Added: `mailtea.emails.list(mode: "test")` reads test-mode mail, and every
+  email carries `mode`. There is no mixed view: a test key reads only test
+  emails and a live key only live ones.
+- Reserved recipients on `test.mailtea.email` force an outcome: `delivered@`,
+  `bounced@`, `complained@`, `delayed@`, `failed@`. The first `to` recipient
+  decides; anything else is delivered.
+
 ## 0.3.0 (2026-09-10)
 
 - Added: `mailtea.domains.update(id, tracking_subdomain: nil)` removes a

data/README.md

@@ -118,7 +118,7 @@ mailtea = Mailtea::Client.new(ENV["MAILTEA_API_KEY"], transport: recorder)
 | `emails.send(params)` | Send a transactional email → `{ "id" => … }` |
 | `emails.batch(emails)` | Send up to 100 emails → `{ "data" => [{ "id" => … }] }` |
 | `emails.get(id)` | Retrieve an email and its delivery status |
-| `emails.list(params = nil)` | List emails → `{ "data", "total", "limit", "offset", "has_more" }` |
+| `emails.list(params = nil)` | List emails → `{ "data", "total", "limit", "offset", "has_more" }`. Pass `mode: "test"` for test-mode mail |
 | `emails.update(id, params)` | Reschedule a scheduled email |
 | `emails.reschedule(id, scheduled_at)` | Convenience wrapper over `update` |
 | `emails.cancel(id)` | Cancel a scheduled email (`POST /v1/emails/:id/cancel`) |
@@ -147,7 +147,7 @@ mailtea = Mailtea::Client.new(ENV["MAILTEA_API_KEY"], transport: recorder)
 | `domains.tracking.create / list / verify / delete` | Manage CNAME tracking sub-domains under a domain |
 | `webhooks.create / list / get / update / delete` | Manage outbound event subscriptions |
 | `contact_properties.create / list / update / delete` | Manage custom contact fields (team-scoped) |
-| `api_keys.create / list / revoke` | Manage API keys (`settings:write`) |
+| `api_keys.create / list / revoke` | Manage API keys (`settings:write`). `create(mode: "test")` mints a test key |
 | `automations.create / list / get / update / delete` | Manage automation graphs (`steps` + optional `connections`) |
 | `automations.validate(params)` | Dry-run a graph → `{ "valid", "issues" }` (no automation needed) |
 | `automations.activate / pause / archive` | Lifecycle (`cancel_runs` defaults **false** on pause, **true** on archive) |
@@ -167,6 +167,35 @@ take none.
 on their resource object, because the API's verb is "send". Ruby's `__send__`
 is untouched, so metaprogramming still works.
 
+## Test mode
+
+A test key (`mt_test_…`) sends nothing. Every message it creates is validated,
+recorded and emits webhooks, but is never handed to a provider — so CI can point
+at production Mailtea with your real code and your real webhook handler.
+
+```ruby
+key = mailtea.api_keys.create(name: "CI", mode: "test")
+# key["token"] starts with mt_test_
+
+test = Mailtea::Client.new(key["token"])
+test.emails.send(
+  from: "you@yourdomain.com",
+  to: "bounced@test.mailtea.email",
+  subject: "Bounce handling",
+  html: "<p>Never delivered.</p>"
+)
+
+page = test.emails.list(mode: "test")
+```
+
+Reserved recipients on `test.mailtea.email` force the outcome — `delivered@`,
+`bounced@`, `complained@`, `delayed@`, `failed@` — and the first `to` recipient
+decides. Every email carries `mode`. A test key reads only test mail and a live
+key only live mail; there is no mixed view.
+
+A test key is **not** a data sandbox. It reads and writes your real contacts,
+templates, senders and webhooks. Only delivery is simulated.
+
 ## Webhooks
 
 Mailtea signs every outbound webhook with

data/lib/mailtea/api_keys.rb

@@ -11,7 +11,13 @@ module Mailtea
     # Create an API key. The +token+ is returned ONCE — store it securely.
     #
     # Takes +name+, optional +permission+ ("full_access" or "sending_access"),
-    # and optional +domain_id+.
+    # optional +domain_id+, and optional +mode+.
+    #
+    # +mode+ is "live" (the default) or "test". A test key is prefixed
+    # <tt>mt_test_</tt>: its sends are validated, recorded and emit webhooks but
+    # are never delivered, and it reads only test mail. It is NOT a data sandbox
+    # — it reads and writes your real contacts, templates, senders and webhooks.
+    # Only delivery is simulated.
     def create(params = nil, **fields)
       request("POST", "/v1/api-keys", payload(params, fields))
     end

data/lib/mailtea/emails.rb

@@ -90,9 +90,15 @@ module Mailtea
       email
     end
 
-    # List emails (most recent first). Optional filters: +status+, +tag_name+,
-    # +tag_value+, +search+ (substring match on recipient/sender/subject),
-    # +from_date+, +to_date+, +limit+, +offset+.
+    # List emails (most recent first). Optional filters: +status+, +mode+,
+    # +tag_name+, +tag_value+, +search+ (substring match on
+    # recipient/sender/subject), +from_date+, +to_date+, +limit+, +offset+.
+    #
+    # +mode+ is "live" or "test" — there is no mixed view. A test key reads only
+    # test mail and a live key only live mail, so this filter matters to a
+    # session-backed credential; asking for the mode your key is not in is an
+    # error rather than an empty list. Every returned email carries its own
+    # +mode+.
     #
     # +from_date+ is clamped to the plan's analytics retention window — 30 days
     # on most plans, 90 on Scale and Enterprise. A value reaching further back

data/lib/mailtea/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mailtea
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtea
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Mailtea
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-10 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies: []
 description: 'The official Ruby SDK for Mailtea: a thin, zero-dependency wrapper over
   the Mailtea REST API, built on net/http and json.'