feat: purpose, folders, preparation status and idempotent sends (TPL-2543, TPL-2539)

[voj-tech-j]

Release 1.5.0. Last of the five in TPL-2543/TPL-2539, level with lettr-php 2.7.0, node, python, go and java. Everything is additive.

client.folders.list()

The one that unblocks the rest. CreateTemplateOptions::with_folder_id has existed for ages, but nothing in the SDK ever returned a folder id.

let folders = client.folders
    .list(ListFoldersOptions::new().purpose(TemplatePurpose::Campaign))
    .await?;

client.templates.create(
    CreateTemplateOptions::new("October Newsletter")
        .with_json(topol_json)
        .with_folder_id(folders.folders[0].id)
        .with_purpose(TemplatePurpose::Campaign),
).await?;

Read-only: deleting a folder moves or deletes the templates inside it.

TemplatePurpose and TemplatePreparationStatus

Both follow the shape CampaignStatus already set in this crate — an Unknown(String) variant so a value added server-side deserializes rather than failing — with #[serde(default = ...)] on each field so an absent one reads as the pre-existing behaviour.

Ready is the default, not Pending — on an API deployment that predates the field every template with HTML was simply usable, and Pending would look like a stalled queue and hang anything waiting for readiness.

is_settled(), not is_ready() — deliberately. It answers "is what I sent what will go out", which is not "can I send this": after an update the previous render stays in place, so a pending template is still sendable while serving the old content.

ListTemplatesOptions::folder_id

One per_page(100) call reconciles a whole bulk import instead of a detail call per template, each dragging the full HTML payload against the same rate limit. A folder outside the resolved project is a 404, not an empty list.

Idempotent sends

let response = client.emails.send(
    CreateEmailOptions::new(from, to, subject)
        .with_html(html)
        .with_idempotency_key("order-confirmation-12345"),
).await?;

response.replayed; // true → replayed an earlier send, no second email went out

The key lives on CreateEmailOptions, not as a send argument. That way send and send_with_quota both pick it up and neither signature changed — Rust has no optional parameters, so adding one would have broken every caller to serve a minority of calls, and a third send_with_idempotency_key would have made it combinatorial with the quota variant. It is #[serde(skip)], so the request body stays byte-identical, and there's a test asserting exactly that.

You choose the key; the SDK never generates one. It only works if both attempts use the same value, and the SDK does not retry — one send is one HTTP request — so the retry is yours. A malformed key returns Error::Validation before any request goes out; is_valid_idempotency_key is public for callers deriving keys from their own ids.

Error::is_idempotency_in_progress() (retry with the same key after Error::retry_after() seconds) and Error::is_idempotency_conflict() (that key was used with a different payload — retrying fails forever). Retry-After is read in Config::send before text() consumes the response.

Checks

cargo test — all 17 suites pass, including doctests. cargo clippy --all-targets -- -D warnings and cargo fmt --check clean.

New: tests/folders_test.rs (shape, every filter, the pre-field default), tests/preparation_status_test.rs (all three statuses in one list call, both filters, the pre-field default, is_settled semantics), tests/idempotency_test.rs (key format, and that setting a key leaves the serialized body byte-identical).

Cargo.toml bumped to 1.5.0 and a CHANGELOG entry added. Not tagged.

🤖 Generated with Claude Code

https://claude.ai/code/session_016uJ8Gsfq5iEPsJv6GxHUgU