[tomasmartty]

Why?

The API has new endpoints to build emails with the simple editor, and the Python SDK did not support them. This PR adds these endpoints, the brand styles and the file list, so that SDK users can create and edit simple editor emails without raw HTTP calls.

Changes

1. Emails (mailerlite/sdk/emails.py): a new client.emails resource with these methods:
   • Reads: get, get_html, get_block, list_versions.
   • Block writes: create_block, update_block, delete_block, move_block, validate_block.
   • Settings: update_settings, validate_settings.
   • Other writes: create_template, create_version, restore_version.
   • The constants BlockType, BlockPosition, BrandMode, VERSION_CONFLICT and EDITOR_SIMPLE.
2. Etags and idempotency keys: each write needs the etag from the last response. A write with an old etag raises ApiError with the code version_conflict and the current etag. Each write accepts an optional idempotency_key, so you can retry it safely after a network error. The SDK sends the etag and the key as the caller gives them, and the API checks them.
3. Campaigns (mailerlite/sdk/campaigns.py): create() documents editor: "simple" and template_id for the emails of a campaign.
4. Brand styles and files: the new methods client.brand_styles.get() and client.files.list().
5. Errors (mailerlite/exceptions.py): ApiError is a subclass of requests.HTTPError. It has status_code, message, code, etag and errors. Before the request, the SDK checks only the IDs in the URL path and the settings of update_settings. It sends all other values as the caller gives them, and the API checks them. The new errors are EmptyIdError and InvalidIdError.
6. Responses (mailerlite/response.py): ApiResponse is a dict with the decoded body, status_code, headers and is_idempotent_replay.
7. HTTP client (mailerlite/api_client.py):
   • It supports PATCH.
   • It sends a JSON body for DELETE when there is a body.
   • It accepts extra headers for one request.
   • A POST, PUT or PATCH request without a body now sends no body, not the JSON null.
8. Shared helpers (mailerlite/sdk/_params.py): a new private module with the ID check, the dict check, the filter parameters and the idempotency key header, so that all resources can use them.
9. Tests: a mock_api fixture records the prepared requests, so the new tests send no request to the network. There are new tests for emails, brand styles, files, the API client, ApiResponse and _params, with JSON fixtures in tests/fixtures.
10. Docs and version: the Readme has examples for each new method. The version is now 0.3.0.

Code review fixes

A code review found 9 issues. Each fix is a separate commit with a test that failed before the fix:

1. f54b214: a write without a body sent the JSON null. This affected emails.create_version, campaigns.cancel and campaigns.activity.
2. e37ce80: an ApiError failed to unpickle, for example in a multiprocessing or Celery worker.
3. 59f0071: placement["block_id"] now gets the same check as the IDs in the URL path, and the SDK sends it as a string.
4. cbc40e5: create_block and validate_block now raise TypeError when block_type is not a str.
5. 29ccdb2: update_settings and validate_settings now raise ValueError when settings contains etag. Before this fix, the etag argument silently replaced that key.
6. 883dc4f: the Idempotent-Replayed header check now ignores case.
7. 53b0df0: the helpers moved from emails.py to mailerlite/sdk/_params.py.
8. 2cc2626: files.list now uses the shared helpers and the new filter_params helper.
9. 34f20d4: a docstring correction.

A later commit, 87b473d, removes the checks of fixes 3 and 4 and the validate_settings part of fix 5. The SDK now sends these values as the caller gives them, and the API checks them. update_settings still raises ValueError when settings contains etag, because the SDK adds the etag to that dict.

Risks

• Older methods without a body: campaigns.cancel and campaigns.activity now send no body. Before, they sent the JSON null. A recorded response shows that the API accepted that body, so the risk is low. The end-to-end test did not call these two methods.
• Errors: the SDK now raises ApiError and not a plain requests.HTTPError. ApiError is a subclass of requests.HTTPError, so code that catches HTTPError continues to work.
• New checks: the checks of the IDs in the URL path and of the settings of update_settings raise errors before the request. Only the new email methods and files.list have them, so existing calls do not change.
• Older list() methods: they still have their own copy of the filter code. A follow-up PR can change them to use _params.filter_params.

Performance impact

No performance impact. Each method sends one request. The new checks are regular expressions on short strings.

Security impact

The SDK sends no new data and has no new authentication. The ID checks make security better: an ID such as 123/html or 123%2Fhtml raises InvalidIdError, so it cannot change the URL path. The SDK sends the idempotency key as the caller gives it. If a key can break a header, for example a key with a new line, requests raises requests.exceptions.InvalidHeader and sends no request.

How to QA

1. Run the unit tests: .venv/bin/python -m pytest -q. The expected result is 300 passed, 1 skipped.
2. Optionally, run the SDK against a development instance of the API. Set client.api_client.HOST to the URL of that instance, then create a campaign with "editor": "simple" and call the email methods on its email.

I did step 2 against a development instance of the API, and all 20 checks passed:

• Reads: brand_styles.get, files.list with a filter, a sort and a limit, emails.get with a str and an int ID, and emails.get_html.
• Campaign: campaigns.create with the simple editor.
• Blocks: validate_block (valid and invalid), create_block, get_block, update_block, move_block and delete_block.
• create_block with an int placement["block_id"]. The API put the block after the correct block.
• Idempotency: a retry with the same idempotency key returned the same block, and is_idempotent_replay was True.
• Version conflict: an old etag raised ApiError with 409 version_conflict and the current etag. The error survived a pickle round trip.
• Settings: validate_settings and update_settings. An etag key in settings raised ValueError before the request.
• Versions: create_version returned 201, and then 200 when nothing had changed, with no body sent. list_versions and restore_version also passed.
• Checks before the request: block_type values None and 5 raised TypeError. A later commit removed this check.
• Cleanup: campaigns.delete deleted the test campaign. A later get returned 410.

This run was before the commit that leaves value checks to the API (87b473d). That commit has unit tests only.

The end-to-end test did not call create_template, because the API cannot delete templates. create_template has unit tests only.

The VCR cassette tests of the older resources do not need QA. This PR does not change them.

How to release

Do not release yet. Release after the public API docs for these endpoints are live.

1. Merge the PR.
2. When the docs are live, push the tag v0.3.0 on main. The Publish to PyPI workflow runs on tags that match v[0-9]+.[0-9]+.[0-9]+*.

There are no migrations, configuration changes or feature flags.

Rollback strategy

• Migrations: none.
• Data changes: none. This PR changes only the SDK.
• External dependencies: no new dependencies.
• Configuration: none.
• Rollback: revert the PR. If 0.3.0 is on PyPI, yank 0.3.0, and tell users to pin 0.2.0.

Screenshots, recordings

N/A

I used AI to generate parts of this PR

Yes

🤖 Generated with Claude Code

[mailerlite-kritika]

Confidence Score: 4/5

[Medium risk] campaigns.cancel and campaigns.activity now send no body, and nothing the review read shows that the API accepts a body-less POST for them; the description's evidence is a recording of the old JSON null body, and the end-to-end run did not call either method. The risk stays medium because the change is a routine request-building change that a revert undoes, and the new ApiError is still an HTTPError subclass.

Summary

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

The change adds client.emails, client.brand_styles and client.files, which return ApiResponse (a dict with status code and headers). It also adds ApiError (a requests.HTTPError subclass) and PATCH and DELETE-with-body support in ApiClient. A body-less POST, PUT or PATCH now sends no body instead of JSON null, which also changes campaigns.cancel and campaigns.activity. The newest commits make ApiResponse return {} for an empty body and raise TypeError for a non-object body. They also add a copy() that keeps the status and headers, drop None filters in filter_params, and check settings in validate_settings the same way as in update_settings.

Flow

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Caller uses client.emails, brand_styles or files"] --> B["Check path IDs, settings dict and filter in _params"]
    B -->|invalid| E["Raise error before any request"]
    B -->|valid| C["ApiClient sends request with etag, placement and idempotency key as given"]
    C --> D{"Response status"}
    D -->|success| F["Return ApiResponse: empty body gives empty dict, non-object body raises TypeError"]
    D -->|error| G["Raise ApiError with code, etag and errors"]

Loading

What's good

• Path IDs are checked with fullmatch on ASCII digits, so IDs like 123/html, 123%2Fhtml or a trailing newline cannot change the URL.
• ApiError defines __reduce__, so it survives pickling, and a test covers the round trip.
• The mock_api fixture records prepared requests, so the new tests cannot reach the network.

Review context · 0/5 commands

• Commands run: none

_{Reviews (6) · Last reviewed commit: "feat: Improvements" · claude-sonnet-5-5}