Skip to content

Upgrading to 0.5.0

Greg Svoboda edited this page Oct 28, 2026 · 1 revision

Upgrading to 0.5.0

Version 0.5.0 fixes several bugs, adds a few endpoints, and changes a small number of behaviours. Nothing was removed or renamed, and new arguments were added at the end of existing signatures, so code written for 0.4.x keeps working. This page lists what to look for when you upgrade.

pip install --upgrade postmark-python

Check these first

If your code does this What changes What to do
Passes client_name, client_company, client_family, os_name, os_family or os_company to outbound.list_opens() / list_clicks() These filters now work. In 0.4.x they were sent with a name Postmark ignores, so you always got unfiltered results. Check the results you expect. If you were relying on the unfiltered list, remove the argument.
Passes from_date or to_date to list_opens() / list_clicks() They never had an effect (Postmark has no date filter on these endpoints). They are still accepted, but now emit a FutureWarning and are not sent. Remove the arguments, and filter by received_at in Python if you need a date range. If your tests run with warnings turned into errors (-W error), they will fail until you do.
Calls webhooks.edit(), or mocks it in tests edit() now makes one extra GET before the PUT. If you mock the HTTP layer, add a response for GET /webhooks/{id}. Real calls need no change.
Reads SendResponse.to, .submitted_at or .message_id Typed str | None / datetime | None (see below). Type checkers may now ask you to handle None.
Reads BounceTypeCount.type or .type_code Typed str | None / int | None. Same.

Behaviour changes in detail

Opens and clicks filters now filter

# 0.4.x: returned every open, as if client_family were not there
# 0.5.0: returns only opens from Gmail
result = await client.outbound.list_opens(client_family="Gmail")

The other filters (recipient, tag, platform, country, region, city, message_stream) were already correct.

webhooks.edit() really is a partial update

In 0.4.x the docstring said "only fields you provide are changed", but Postmark requires the URL on every update, so an edit without url failed. In 0.5.0 edit() reads the current webhook, merges your changes, and sends the complete configuration. See Webhooks.

Batch sends return failures instead of raising

In 0.4.x, if any entry in send_batch() or send_batch_with_template() failed, parsing the response raised and you lost the results of the entries that were sent. In 0.5.0 every entry comes back, in order, and you check success:

for r in await client.outbound.send_batch(messages):
    if r.success:
        print("sent", r.message_id)
    else:
        print("failed", r.error_code, r.message)

Typing-only changes

These affect type checkers (mypy, pyright), not runtime behaviour. For successful sends the values are still filled in exactly as before.

  • SendResponse.to, .message_id: str | None; .submitted_at: datetime | None. They are None for a failed batch entry. Narrow them before use:

    response = await client.outbound.send(email)
    assert response.message_id is not None   # or: if response.message_id: ...
  • BounceTypeCount.type: str | None, and .type_code: int | None. The All total entry in get_delivery_stats() has neither.

  • PushTemplatesRequest.source_server_id / .destination_server_id: int | str (was str). Whatever you pass is sent unchanged.

Things that used to raise and now work

No action needed, but if you worked around these, you can remove the workaround:

  • outbound.send_bulk() raised a ValidationError even though Postmark had accepted and sent the request. It now returns the bulk request ID (response.id).
  • BulkJobStatus has a new CANCELLED member. A cancelled bulk request used to fail to parse. FAILED is kept for compatibility.
  • bounces.get_delivery_stats() raised because of the All entry.
  • stats.platform_usage(), stats.browser_platform_usage() and stats.click_location() raised on any day where a category had no activity. Postmark leaves out zero counts; they now read as 0.
  • templates.push() rejected integer server IDs.

New in 0.5.0

What Where
List your bulk requests, with cursor pagination outbound.list_bulk_requests() and outbound.stream_bulk_requests()
Verify a webhook and see how your endpoint answered webhooks.verify()
Delivery statistics for a webhook webhooks.get_statistics()
Save a webhook without verifying it first webhooks.create(..., verify=False) / webhooks.edit(..., verify=False)
Each trigger's verification status status on wh.triggers.<name> (Webhooks)
Filter templates by the layout they use templates.list(layout_template="alias")
A cursor-based page type postmark.CursorPage (items, next_key)

Dependencies and supported versions

Unchanged: Python 3.10 or newer, and the same dependency ranges (for example pydantic>=2.6.0,<3.0.0). Nothing you pin needs to move.

Something not working after upgrading?

Please open an issue with the code that changed behaviour and the versions before and after. For anything security-related, use the private reporting described in the repository's SECURITY.md instead of a public issue.

Clone this wiki locally