mailtea 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d690859b9a966c7c3446b88a8ad18eaa3c403af32137d7e15e8aab72294cd79e
-  data.tar.gz: 9227bf62c989dce0a000d90433eb769d2762ba515614bbe037bb1b2cfbc4d0df
+  metadata.gz: 3539cea90528dd0db53f91ddaf0897c093ce83f6ec75ccac90666ba24fb6dcd9
+  data.tar.gz: e1f33edadd5e115d42f3d3294d589034d76bb29e870dbe5c952c06fc11fab42e
 SHA512:
-  metadata.gz: 407fd01f8e7850bb13e4042955f4bdde236190f61a431718d3a76276218e92564bb1ee882bbbaca096c0239b72f60e1b4eb986c7b18111827a2822e1a3b75e1e
-  data.tar.gz: 5fb8f59e24537373bb3756257954c859cef61043cc3dd54478fe15720a53d77002a01898ba8867891d28454c7f8fa01620cbbf415209c667f80ea7d9b1c9a92e
+  metadata.gz: abc137144ae2f95a8a881005409eeff50142404f8b9ba35043482f2780d80c4e2e887263c1953c16b79f39bbd3ec364c484e8cd95c0541978c1d3746a3878c56
+  data.tar.gz: 56f72ee40bb049f99e4d95fc58c78539fa6da22109b25d6bbf7c6af87a08fa9109e7cb33f3bd72a787e6559067f5db97f6382ab00372b9b42ae8866e1db16b14

data/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 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

data/README.md

@@ -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) |

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/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.4.0"
+  VERSION = "0.5.0"
 end

metadata

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