mailtea 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98e959c77cb6dc2c7b99cff06807b2c18052d6147bd03ec4b8256f89c88859e9
-  data.tar.gz: 814086291d3c3937eb1cadeae73500add856b67f4f28ea1105a3ddceb4fceb9b
+  metadata.gz: 3539cea90528dd0db53f91ddaf0897c093ce83f6ec75ccac90666ba24fb6dcd9
+  data.tar.gz: e1f33edadd5e115d42f3d3294d589034d76bb29e870dbe5c952c06fc11fab42e
 SHA512:
-  metadata.gz: b0cc04ddef836710cfc8690c8c4fee4fc400e04603be449d491024eaeac2a5c3b4558d31fd32bd8e509d4ec7e5c07cc1f48160d75b995fb45fca7514c217e807
-  data.tar.gz: 2fa9199a5dded8c0b80024fe49fe54d82c1bb037cf96fe15d02f4c4ff20ed6d7e2b1064a167c1eaf83c9d83fce065e1e0c047e7602977ec9eff15029df1dac83
+  metadata.gz: abc137144ae2f95a8a881005409eeff50142404f8b9ba35043482f2780d80c4e2e887263c1953c16b79f39bbd3ec364c484e8cd95c0541978c1d3746a3878c56
+  data.tar.gz: 56f72ee40bb049f99e4d95fc58c78539fa6da22109b25d6bbf7c6af87a08fa9109e7cb33f3bd72a787e6559067f5db97f6382ab00372b9b42ae8866e1db16b14

data/CHANGELOG.md

@@ -2,6 +2,98 @@
 
 All notable changes to the `mailtea` Ruby gem are documented here.
 
+## 0.5.0 (2026-09-28)
+
+- Breaking: `Posts#create` with `template_id` now HTML-escapes the `variables`
+  you pass, the same as every other send. HTML passed in a `{{key}}` value now
+  arrives as visible text, and a value you escaped yourself arrives
+  double-escaped. Put `{{{key}}}` in the template where a value is meant to be
+  raw HTML. Variables are now filled in both the `{{key}}` and Visual Email
+  Designer `{key}` forms. A declared variable you do not pass stays in the
+  post with its `fallback_value`, so the broadcast gives each recipient their
+  own value or that fallback, and undeclared tokens like
+  `{{contact.first_name}}` are left for the broadcast too. The post keeps the
+  template's published page style, is wrapped in that page, and has its
+  show-if blocks decided per recipient when it is sent. Before, only the
+  variables you passed were replaced, raw, and only in `{{key}}` form. It uses
+  the template's published version; Mailtea Studio's "Use template" starts
+  from the latest saved design instead.
+- Changed: `Templates#update` and `Templates#restore_version` no longer move a
+  published template back to draft. The template keeps its published status,
+  and automations and the API keep sending its published version until
+  `Templates#publish` is called again. The template's `from` and `reply_to`
+  are part of the published version too, so a new sender or reply-to address
+  reaches sends only after the next publish. `Templates#unpublish` is now the
+  only way to stop a published template sending, short of deleting it, and it
+  drops the stored published version so the next publish starts from the
+  current content.
+- Added: `has_unpublished_versions` on every returned template hash. True only
+  when the template is published and its saved content (From, Reply-To and the style profile
+  included) differs from the published version.
+- Added: `is_published` on each template version entry: true for the one entry
+  automations and the API are sending now. `is_current` is now described as
+  what it is: the entry that matches the working copy (the saved design being
+  edited), not necessarily what is sending. `is_published` is false on every
+  entry of a draft, and on a template published before the field existed until
+  it is published again.
+- Changed: the `unpublished` key on the update and restore replies is kept for
+  compatibility and is now always `false`. Check `has_unpublished_versions`
+  (or the reply's `message`) instead.
+- Changed (API behavior): a template variable's `fallback_value` can no longer
+  contain `{` or `}`. Creating a template with one, or changing a fallback
+  to one on update, is a 400 ("Fallbacks can't contain { or }."). A value
+  the template already stores is accepted unchanged, so a template saved
+  before the rule keeps saving. Inline chip fallbacks such as
+  `{first_name|Mom & Pop}` now render as written instead of double-escaped.
+- Changed (API behavior): saving an active automation is refused only when the
+  edit adds an error the live version does not already have. The 422
+  `active_graph_invalid` reply's `issues` lists just those new problems.
+  Before, any error refused the save, even one the live version already had.
+  Starting refuses every error as before, except an `unknown_step_ref` at a
+  `config.*` path or a trigger `missing_branch` that the version the
+  automation last ran on already had, so pausing and starting an unchanged
+  automation keeps working. Issues the last live version already had come back
+  with `pre_existing: true`.
+- Added (API behavior): issue objects carry `field`, what a rule reads (the
+  rule's `field`, or the path in a `{"var": ...}` value, e.g.
+  `steps.welcome.opened`) when the issue is about one.
+- Changed (API behavior): two issues are the same problem when their code and
+  step match, and their `field` or, when there is none, their `path`. Moving
+  a rule, by removing a rule beside it or putting it in a group, no longer
+  makes a problem the live version already had look new. An error is
+  `pre_existing` only if the live version had an error there, not a warning.
+- Changed (API behavior): `validate_only` on an active automation answers the
+  way the save would. A trigger change is a 422 `trigger_locked_while_active`,
+  a change that adds a problem is a 422 `active_graph_invalid` listing only
+  the new problems, and otherwise issues come back with `pre_existing` marked
+  against the version live now. Before, it returned every issue unmarked.
+- Changed (API behavior): changing the trigger (its type or key) of an active
+  automation is now refused with 422 `trigger_locked_while_active`. Pause it
+  first; draft and paused automations can still change their trigger. Before,
+  the change was accepted.
+- Added (API behavior): new validation rules. A trigger with nothing after it
+  is a `missing_branch` error at `branches.next`. A rule or `{"var": ...}`
+  value that reads `steps.<key>.*` for a step that isn't in the automation is
+  an `unknown_step_ref` error at that `config.*` path, or a warning when the
+  `{"var": ...}` has a `default`. A rule or value that reads
+  `event.properties.*` when the automation does not start from an app event is
+  the new warning `event_field_without_event_trigger`.
+
+## 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`) |
@@ -139,7 +139,7 @@ mailtea = Mailtea::Client.new(ENV["MAILTEA_API_KEY"], transport: recorder)
 | `templates.create / list / get / update / publish / unpublish / duplicate / delete` | Manage reusable email templates |
 | `templates.render(params)` | Render a spec to HTML without saving → `{ "html", "text" }` |
 | `templates.versions(id, params = nil)` | List a template's design history, newest first (metadata only) |
-| `templates.restore_version(id, version, params = nil)` | Put an older design back — a content write, so the template returns to **draft** |
+| `templates.restore_version(id, version, params = nil)` | Put an older design back as unpublished changes; a published template keeps sending its published version until you `publish` again |
 | `assets.upload / list / delete` | The publication's image library (raw bytes are base64-encoded for you) |
 | `suppressions.list / add / remove` | Manage the team-wide do-not-send list |
 | `suppressions.export` | Export the whole suppression list as CSV (raw text) |
@@ -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/automations.rb

@@ -59,7 +59,11 @@ module Mailtea
     #
     # <tt>validate_only: true</tt> returns an +automation_validation+ and writes
     # nothing. A graph change that carries errors saves anyway while the
-    # automation is draft/paused/archived; on an +active+ one it is a 422 —
+    # automation is draft/paused/archived. On an +active+ one it is a 422
+    # +active_graph_invalid+ only when it adds an error the live version does
+    # not already have; +issues+ then lists just those new problems, and older
+    # ones come back with <tt>pre_existing: true</tt>. Changing an +active+
+    # automation's trigger is a 422 +trigger_locked_while_active+. Either way:
     # pause, save, then start again.
     def update(id, params = nil, **fields)
       scope, body = Util.split_publication(payload(params, fields), keep_in_body: false)
@@ -75,7 +79,9 @@ module Mailtea
 
     # Start the automation so new contacts enroll. Requires +publication_id+. A
     # graph with errors is refused with 422 +automation_invalid+ and the
-    # blocking +issues+.
+    # blocking +issues+, except an +unknown_step_ref+ at a <tt>config.*</tt>
+    # path or a trigger +missing_branch+ that the version it last ran on
+    # already had (<tt>pre_existing: true</tt>).
     def activate(id, params = nil, **filters)
       request("POST", "/v1/automations/" + escape(id) + "/activate" + query(payload(params, filters)))
     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/posts.rb

@@ -7,10 +7,19 @@ module Mailtea
   # <tt>mailtea.posts</tt>.
   class Posts < Resource
     # Create a newsletter post (a draft by default). Seed it from a published
-    # server template with +template_id+ + +variables+, or pass inline +html+.
-    # +kind+ selects the post type ("newsletter" or "broadcast"). Set
-    # <tt>send: true</tt> to deliver right after creating (or with
-    # +scheduled_at+ to schedule) — that requires the +issues:send+ scope.
+    # server template with +template_id+ + +variables+, using the template's
+    # PUBLISHED version and not any unpublished edits saved since, or pass
+    # inline +html+. The +variables+ you pass are filled in, in both the
+    # <tt>{{key}}</tt> and Visual Email Designer <tt>{key}</tt> forms, and
+    # HTML-escaped (use <tt>{{{key}}}</tt> in the template for raw HTML).
+    # Everything else is left for the broadcast to fill per recipient: a
+    # declared variable you do not pass keeps its +fallback_value+ for
+    # recipients with no value, and undeclared tokens like
+    # <tt>{{contact.first_name}}</tt> stay as they are. The post keeps the
+    # template's published page style. +kind+ selects the post type
+    # ("newsletter" or "broadcast"). Set <tt>send: true</tt> to deliver right
+    # after creating (or with +scheduled_at+ to schedule); that requires the
+    # +issues:send+ scope.
     #
     # Returns <tt>{ "id" => ... }</tt>.
     def create(params = nil, publication_id: UNSET, subject: UNSET, html: UNSET,

data/lib/mailtea/templates.rb

@@ -46,6 +46,13 @@ module Mailtea
     # +global_css+, +category+, +preview_image_url+, +tags+, +text+, +subject+,
     # +from+ and +reply_to+ accept +nil+ to clear them. +publication_id+ is
     # required and goes in the query string.
+    #
+    # Editing a published template no longer unpublishes it: the change is
+    # saved as the working copy, the template keeps its published status, and
+    # the published version keeps sending until #publish is called again. The
+    # reply's +unpublished+ is kept for compatibility and is always +false+
+    # now; check +has_unpublished_versions+ on the reply instead (it also
+    # carries +message+ when that is +true+).
     def update(id, params = nil, **fields)
       scope, body = Util.split_publication(payload(params, fields))
       request("PATCH", "/v1/templates/" + escape(id) + scope, body)
@@ -57,8 +64,11 @@ module Mailtea
     end
 
     # Return a published template to draft. +published_at+ is kept — it records
-    # that the template was published once, not that it still is. Requires
-    # +publication_id+.
+    # that the template was published once, not that it still is. This is now
+    # the only way to stop a published template sending, short of deleting it
+    # (editing or restoring it no longer does that on its own). It also drops
+    # the published version, so the next #publish starts from the current
+    # (working) content. Requires +publication_id+.
     def unpublish(id, params = nil, **filters)
       request("POST", "/v1/templates/" + escape(id) + "/unpublish" + query(payload(params, filters)))
     end
@@ -66,13 +76,18 @@ module Mailtea
     # List a template's design history, newest first. Requires +publication_id+;
     # optional +limit+ (the server caps it at the retained maximum).
     #
-    # Entries are metadata only — +version+, +origin+ ("edit", "publish" or
+    # Entries are metadata only: +version+, +origin+ ("edit", "publish" or
     # "restore"), +restored_from_version+, +format+, +name+, +sealed+,
-    # +is_current+, +created_at+, +updated_at+ and +author+ (or nil) — never the
-    # design document, which one entry alone can carry half a megabyte of.
-    # +is_current+ marks the design the template is serving right now, which is
-    # not always the newest entry: a metadata-only update touches the template
-    # without recording a version.
+    # +is_current+, +is_published+, +created_at+, +updated_at+ and +author+ (or
+    # nil). The design document is never included, because one entry alone can
+    # carry half a megabyte of it. +is_current+ marks the entry that matches the working copy
+    # (the saved design being edited), which is not always the newest entry: a
+    # metadata-only update touches the template without recording a version.
+    # +is_published+ (a boolean) marks the entry automations and the API are
+    # sending now. They differ while a published template has unpublished
+    # changes. +is_published+ is +false+ on every entry of a draft, and on every
+    # entry of a template published before the field existed until it is
+    # published again.
     #
     # The reply also carries +retention+: only the newest +max_versions+ are
     # kept, and consecutive edits by the same author within
@@ -84,10 +99,13 @@ module Mailtea
     # Put an older design from #versions back onto the template. Requires
     # +publication_id+.
     #
-    # *Restoring is a content write, so the template returns to draft* —
-    # automations and the API stop sending it until #publish is called again.
-    # The reply's +unpublished+ reports whether that just happened; re-publishing
-    # is the caller's job.
+    # *Restoring no longer unpublishes the template.* It is a content write,
+    # and lands in the working copy: a published template keeps its published
+    # status and keeps sending its published version until #publish makes the
+    # restored design live. The reply's +unpublished+ is kept for
+    # compatibility and is always +false+ now; check +has_unpublished_versions+
+    # on the returned +template+ (or the reply's +message+) to see whether the
+    # restored design is live yet.
     #
     # History is forward-only: the design being replaced is recorded as its own
     # version first, then the restored design is appended as the new newest one.
@@ -96,10 +114,10 @@ module Mailtea
     #
     # Restoring the design that is already current writes nothing and returns
     # <tt>restored: false</tt> with <tt>reason: "identical"</tt> and
-    # <tt>unpublished: false</tt>, so a no-op restore cannot unpublish a live
-    # template. A version that has aged out of retention raises Mailtea::Error
-    # with +code+ "template_version_not_found". Returns +restored+,
-    # +restored_from_version+, +unpublished+, +message+ and the updated +template+.
+    # <tt>unpublished: false</tt>. A version that has aged out of retention
+    # raises Mailtea::Error with +code+ "template_version_not_found". Returns
+    # +restored+, +restored_from_version+, +unpublished+, +message+ and the
+    # updated +template+.
     def restore_version(id, version, params = nil, **filters)
       request(
         "POST",

data/lib/mailtea/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailtea
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Mailtea
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-10 00:00:00.000000000 Z
+date: 2026-09-28 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.'