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

[voj-tech-j]

Release 1.6.0. Fourth of the five in TPL-2543/TPL-2539, level with lettr-php 2.7.0, node, python and go. Everything is additive — code written against 1.5.1 keeps compiling and sends identical requests.

lettr.folders().list()

The one that unblocks the rest. CreateTemplateOptions.folderId() 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.

Folder campaigns = lettr.folders()
    .list(ListFoldersParams.builder().purpose(TemplatePurpose.CAMPAIGN).build())
    .getFolders().get(0);

lettr.templates().create(CreateTemplateOptions.builder()
    .name("October Newsletter")
    .json(topolJson)
    .folderId(campaigns.getId())
    .purpose(TemplatePurpose.CAMPAIGN)
    .build());

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

TemplatePurpose and TemplatePreparationStatus

Gson-annotated enums, on create, on every template response, and as ListTemplatesParams filters.

Both getters default rather than returning null — TRANSACTIONAL and READY — because on an API deployment that predates the fields every template with HTML was simply usable, and a null would push that decision onto every caller. Defaulting to PENDING would make an older API look like a stalled queue and hang anything waiting for readiness.

isSettled(), not isReady() — 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. A name like isReady() invites wiring it into a send guard that blocks legitimate sends.

ListTemplatesParams.folderId()

One perPage(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

CreateEmailResponse response = lettr.emails().send(options, "order-confirmation-12345");
response.isReplayed(); // true → replayed an earlier send, no second email went out

A second send() overload, not a changed signature, so existing single-argument calls are untouched.

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 throws IllegalArgumentException before any request is made; IdempotencyKeys.isValid() is public for callers deriving keys from their own ids.

Two new exceptions extending LettrApiException, so existing handlers keep catching them: IdempotencyInProgressException (carries getRetryAfter(), retry with the same key) and IdempotencyConflictException (that key was used with a different payload — retrying fails forever).

One structural choice worth reviewing

The 409 mapping lives in handleErrorResponse, not in the service — which differs from ContactAlreadyExistsException, where AudienceContacts catches and rewraps. The reason: that exception carries the submitted email, which only the service knows, whereas Retry-After is a transport concern the service never sees. Putting it in the service would have meant plumbing headers out just to throw.

That required threading HttpHeaders through execute → handleErrorResponse. execute() keeps its signature and delegates to a new executeWithHeaders(), and HttpClient gained postWithHeaders() plus a small ApiResponse<T> holder — returning headers rather than storing them, so concurrent calls cannot read each other's.

Checks

./gradlew build passes — compile, tests and checks.

New: FoldersTest (query params, deserialization, the pre-field default, response shape), IdempotencyKeysTest (format, and that validation throws before any request), plus a block in TemplatesTest covering the folder/purpose filters, both filters absent when unset, enum deserialization, the pre-field defaults, isSettled() semantics, and purpose serialized only when set.

gradle.properties bumped to 1.6.0 and a CHANGELOG entry added. Not tagged.

🤖 Generated with Claude Code

https://claude.ai/code/session_016uJ8Gsfq5iEPsJv6GxHUgU