[tomasmartty]

Why?

The MailerLite API adds endpoints to read and edit emails that are built with the simple editor. It also adds two related endpoints: brand styles and files. This PR adds all 16 endpoints to the Java SDK, so that Java users can build and edit these emails without raw HTTP requests.

Merge and release this only after the endpoints are in the public API documentation.

Changes

1. New Emails service (com.mailerlite.sdk.emails), from ml.emails():

   Method	Endpoint
   get	GET /emails/{email}
   getHtml	GET /emails/{email}/html
   getBlock	GET /emails/{email}/blocks/{block}
   createBlock	POST /emails/{email}/blocks
   updateBlock	PATCH /emails/{email}/blocks/{block}
   deleteBlock	DELETE /emails/{email}/blocks/{block}
   moveBlock	POST /emails/{email}/blocks/{block}/move
   validateBlock	POST /emails/blocks/validate
   updateSettings	PATCH /emails/{email}/settings
   validateSettings	POST /emails/{email}/settings/validate
   createTemplate	POST /emails/{email}/templates
   versions(...).get()	GET /emails/{email}/versions
   createVersion	POST /emails/{email}/versions
   restoreVersion	POST /emails/{email}/versions/{version}/restore

   • The package already had the campaign email models (Email, EmailBase), so the email model is EmailDocument.
   • Required IDs and the etag are method arguments. Request bodies are plain classes with public fields (EmailBlockInput, EmailBlockPosition, EmailSettings).
   • editor_content is a Map<String, Object> with its own Gson adapter. Whole numbers stay whole (linkId: 7 is not sent back as 7.0), and null values in the map are kept.
   • In the settings classes, a null field is not sent. Only a brand colour accepts an empty string, and an empty editor document unsets a footer text.

2. New BrandStyles service (com.mailerlite.sdk.brandstyles): ml.brandStyles().get() calls GET /brand-styles. brand is null when the account has no brand styles.

3. New MediaFiles service (com.mailerlite.sdk.files): ml.files().retriever() calls GET /files, with nameFilter, typeFilter, sort, page and limit. The names do not use File or Files, so that they do not clash with java.io.File and java.nio.file.Files.

4. HTTP layer (MailerLiteApi)

   • The new sendRequest method supports PATCH, a DELETE body (only deleteBlock sends one) and a POST with no body (createVersion). The old request methods do not change.
   • MailerLiteException has new fields: errorCode and etag, a new method, isVersionConflict(), and a new constant, VERSION_CONFLICT. code stays the HTTP status. When the API sends a code, getMessage() starts with it. EmailErrorCodes.VERSION_CONFLICT refers to the constant, so the exceptions package does not import the emails package.
   • The public field MailerLiteException.message now has the message of the API error, without the code. Before, it was always "" (also on main). If the SDK cannot read the error body, or for a network error, it has the same text as getMessage().
   • A network error is now a MailerLiteException with the network error as the cause. Before, all request methods threw a ClassCastException.
   • ApiRequest now encodes the query values and skips null values. This also applies to the old retrievers (see "Upgrading to 0.1.0").

5. Checks before the request: the SDK checks only the IDs in the URL path and the characters of the idempotency key. If a check fails, the SDK throws the error and sends no request.

   • Email, block and version IDs must contain only ASCII digits. Otherwise the SDK throws EmptyIdException or InvalidIdException. Both are unchecked subclasses of IllegalArgumentException. Reason: the API cannot see this problem. It decodes an escaped / in a path, so an escaped ID could reach a different endpoint.
   • The SDK sends all other values as the caller gives them, and the API checks them: the etag, the placement and its block_id, the block type, editor_content and the template name. The SDK does not repeat the API rules, so a rule change in the API needs no SDK release.
   • A null block in createBlock and null settings in updateSettings throw NullPointerException. In validateBlock and validateSettings, a null argument sends an empty body, and the API returns the validation errors.

6. Idempotency keys: the 8 email writes have an overload with a last RequestOptions argument: RequestOptions.idempotencyKey(key). The SDK sends it as the Idempotency-Key header. If a request with the same key already succeeded, the API returns the stored response again and does not do the write two times. This makes it safe to retry a write after a network error. The SDK sends the key as given, and the API checks it (an invalid key gets 400). Only one exception: a key with a character outside printable ASCII (0x20 to 0x7E) throws InvalidIdempotencyKeyException (an IllegalArgumentException), and the SDK sends no request. Reason: the Java HTTP client sends each character that is not ASCII as ?, so k-é-k reached a development instance of the API as the valid key k-?-k, and the write ran. A null or empty key sends no header. MailerLiteResponse.isIdempotentReplay() is true when the API returned a stored response.

7. Campaigns: EmailBase has three new fields: replyTo, editor and templateId. Set editor to EmailEditors.SIMPLE to create an email with the simple editor, and then edit it with ml.emails(). Only create accepts editor and templateId. An update with these fields gets a 422.

8. Constants: block types, block positions, brand modes, the simple editor, the version_conflict error code, file types and file sorts. They are String constants, so a new value from the API does not break the decode.

9. README: a new "Upgrading to 0.1.0" section, new "Emails", "Brand styles" and "Files" sections with one example for each method, a "Retry a write with an idempotency key" example, and "Create a campaign with the simple editor".

10. Version: 0.1.0 in pom.xml and in the README install snippets.

Compatibility

All changes add to the public API. A javap comparison of main and this branch shows no public or protected member that was removed or changed. Some behavior changes, and the README section "Upgrading to 0.1.0" describes each one:

• The SDK now encodes query values. A caller who encoded a value before now gets it encoded two times.
• A + in a query value is now sent as a literal +.
• A subclass of EmailBase with its own reply_to, editor or template_id field now makes Gson throw an error.
• A network error is now a MailerLiteException, not a ClassCastException.
• The field MailerLiteException.message now has a value. Before, it was always "". getMessage() does not change.

Tests

• The new tests use a fake HttpClient that keeps each request and its raw body, and returns queued responses. They use no recorded tapes and no account, and they cannot reach the API.
• Each new method has a test. The test checks the HTTP method, the full URL with the query string, the headers, the exact raw body and the decoded fields.
• Other tests cover these cases:
  • 409 with version_conflict, 422 with errors, and 503 with an HTML body;
  • createVersion with 201 and with 200, and with an empty raw body;
  • brand: null, a file name filter with spaces, and the encoding of an encoded value;
  • each invalid path ID, and that no request is sent;
  • an empty etag, a placement with or without block_id for each position, an empty block type and an empty template name: the SDK sends each one as given, and the test checks the exact body and the API error. A null etag sends no etag key;
  • the idempotency key header, the replay flag (true, True, no header), and keys with spaces, ~ or more than 255 characters. The SDK gives each key to the Java HTTP client as given. The client removes the spaces at the start and the end;
  • keys with é, a CJK character, an emoji, a new line, a tab, DEL or another control character: the SDK throws InvalidIdempotencyKeyException and sends no request;
  • the message field of MailerLiteException for each request method, for an error with a code, for an error body without a message, for an HTML body and for a network error;
  • that the exceptions package does not import the emails package;
  • a network error without a message;
  • the campaign create body: editor and template_id are present, and content is absent.
• mvn test passes on JDK 11 and on JDK 21 (177 tests, 0 failures, 0 errors). All old tests still match their recorded tapes. mvn javadoc:javadoc on JDK 11 gives no warnings.
• Each README example runs in a test against the fake HttpClient.
• All 16 endpoints were also run against a development instance of the API, through the SDK. These runs included a full flow that passes each new etag to the next write, the error cases 409 (old etag), 404 (unknown block) and 422 (invalid file type), and an idempotency check: a retry with the same key returned the stored 201 with the same block ID, the same key with a different body returned 422, and a retry without a key returned 409. These runs were before the change that leaves the value checks to the API.

How to test

1. Run mvn test. pom.xml sets testFailureIgnore, so read the Tests run summary, not the exit code.
2. Get an API token for a test account. Run the README example "Create a campaign with the simple editor", and get the email ID from the response.
3. Run the README examples in this order: "Get an email", "Insert a block", "Move a block", "Delete a block". Pass the etag of each response to the next write.
4. Make sure that a write with an old etag throws a MailerLiteException where isVersionConflict() is true.
5. Run the README example "Retry a write with an idempotency key" two times with the same key and the same etag. Make sure that the second response has the same block ID and that isIdempotentReplay() is true.

How to release

1. Wait until the endpoints are in the public API documentation.
2. Merge, then create the GitHub release v0.1.0. The publish workflow checks that the tag is the same as the version in pom.xml, and then publishes to Maven Central. This is a minor version because of the behavior changes in "Upgrading to 0.1.0".

Rollback

No data or configuration changes. To roll back, revert the merge commit and release a new patch version.

🤖 Generated with Claude Code

[mailerlite-kritika]

Confidence Score: 4/5

[High risk] The description says to merge and release only after the 16 endpoints appear in the public API documentation, and neither the description nor the review's account shows that this was checked; the review read no sources outside the repository. The risk stays high, as in the last review: the change is additive, but it changes existing behavior (query values are now encoded, + is sent literally, network errors are now MailerLiteException, and MailerLiteException.message is now filled), and a …

Findings

Earlier findings (1 resolved, 1 dismissed)

• src/main/java/com/mailerlite/sdk/exceptions/MailerLiteException.java:12 Core exception package depends on the emails package · maintainability · resolved
• src/test/java/com/mailerlite/sdk/tests/MediaFilesTest.java:132 Assertion depends on HashMap iteration order of query parameters · dismissed: thread resolved by tomasmartty

Summary

Adds simple-editor email, brand style and file endpoints to the SDK

The change adds ml.emails(), ml.brandStyles() and ml.files() on a new MailerLiteApi.sendRequest method that supports PATCH, a DELETE body and a bodiless POST. It also adds etag and error-code fields on MailerLiteException, idempotency-key support, and encoding of query values. The commits since the last review move the version_conflict constant into MailerLiteException, so the exceptions package no longer imports emails. They also reject idempotency keys that are not printable ASCII before any request is sent. MailerLiteException.message is now filled from the API error message, and the README upgrade notes describe it.

What's good

• Tests use a recording fake HttpClient that checks the method, URL, headers and raw body for each endpoint.
• The README examples are compiled and run in a test, so the documentation cannot drift from the API.
• The upgrade section lists each behavior change, such as query encoding and network errors, and a test asserts that the exceptions package stays free of emails imports.

Review context · 0/5 commands

• Commands run: none

_{Reviews (5) · Last reviewed commit: "fix: set the message field of MailerLite..." · claude-sonnet-5-5}

[mailerlite-kritika]

Core exception package now depends on the emails package · maintainability

MailerLiteException in exceptions imports com.mailerlite.sdk.emails.EmailErrorCodes only to implement isVersionConflict(). emails already depends on exceptions (Emails imports MailerLiteException), so this creates a package cycle. The cycle ties a generic exception to one service's constants.

Suggested fix

Keep the cycle out by comparing against a constant that lives in exceptions (for example a public static final String VERSION_CONFLICT on MailerLiteException). Make EmailErrorCodes.VERSION_CONFLICT alias it, or the reverse, and drop the emails import here.

Prompt for a coding agent

In MailerLiteException.java remove the import of com.mailerlite.sdk.emails.EmailErrorCodes. Add a constant `public static final String VERSION_CONFLICT_CODE = "version_conflict";` to MailerLiteException and make isVersionConflict() compare against it. Change EmailErrorCodes.VERSION_CONFLICT to reference MailerLiteException.VERSION_CONFLICT_CODE so the value stays defined in one place. Update the Javadoc {@link} on isVersionConflict accordingly.