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

[voj-tech-j]

Release 1.6.0. Brings this client level with lettr-php 2.7.0 and lettr-node. Everything is additive — code written against 1.5.1 keeps working and sends identical requests.

client.folders.list()

The one that unblocks the rest. templates.create(folder_id=...) has existed for ages, but nothing in the SDK ever returned a folder id — so a caller either omitted it and accepted whichever folder the API picked, or hardcoded an integer read out of an app URL.

campaigns = client.folders.list(purpose="campaign").folders[0]

client.templates.create(
    name="October Newsletter",
    json=topol_json,
    folder_id=campaigns.id,
    purpose="campaign",
)

Read-only by design: deleting a folder moves or deletes the templates inside it, so that stays in the app.

Template purpose and preparation_status

purpose ("transactional" | "campaign") on create, on every response, and as a list filter. preparation_status ("pending" | "ready" | "failed") on every response.

Two things about the status that are easy to get wrong, and are commented in the code:

• It is not "can I send this". After an update the previous render stays in place, so a "pending" template is still sendable — it is serving the old content.
• A missing key reads as "ready", not "pending". It comes from an API deployment that predates the field, where every template with HTML was simply usable. Defaulting to "pending" would make an old API look like a stalled queue and hang anything waiting for readiness.

templates.list(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 raises NotFoundError rather than returning an empty list — a typo cannot be misread as "nothing is there yet".

Idempotent sends

result = client.emails.send(..., idempotency_key="order-confirmation-12345")
result.replayed  # True → replayed an earlier send, no second email went out

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, and only you know two calls are the same logical send. A key minted inside send() would differ on every attempt and protect nothing while looking like it did.

A malformed key raises ValidationError before any request goes out. is_valid_idempotency_key() is exported for callers deriving keys from their own ids.

Two new exceptions under ConflictError, because one is safe to retry and the other is not:

• IdempotencyInProgressError — carries retry_after; retry with the same key.
• IdempotencyConflictError — that key was used with a different payload. Caller bug; retrying fails forever.

Two implementation notes worth a look

A keyless send takes the plain post() path. Without a key there is nothing to replay, so replayed is definitionally False and reading response headers would be dead weight. It also means every existing test double keeps working untouched — which is how I found the shape.

ApiClient gained request_with_headers() / post_with_headers() for the one place a response header carries meaning. Separate methods rather than state on the client, so two calls cannot read each other's headers. request() and post() are unchanged, and raise_for_status() takes an optional third headers argument that existing two-argument calls ignore.

Checks

pytest — 179 passed. ruff check, ruff format --check and mypy src all clean.

New: tests/test_folders.py (shape, every filter, the pre-field fallback, reachable from the client), tests/test_idempotency.py (key format, local rejection before any request, header not body, replay detection case-insensitively, both 409s, and that raise_for_status still works without headers), plus a TestPreparationStatusAndFolderFilter block in tests/test_templates.py.

pyproject.toml bumped to 1.6.0 and a CHANGELOG entry added. _version.py reads from package metadata, so nothing to change there.

Not tagged.

🤖 Generated with Claude Code

https://claude.ai/code/session_016uJ8Gsfq5iEPsJv6GxHUgU