Repository navigation
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| 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. |
# 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.
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.
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)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 areNonefor 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. TheAlltotal entry inget_delivery_stats()has neither. -
PushTemplatesRequest.source_server_id/.destination_server_id:int | str(wasstr). Whatever you pass is sent unchanged.
No action needed, but if you worked around these, you can remove the workaround:
-
outbound.send_bulk()raised aValidationErroreven though Postmark had accepted and sent the request. It now returns the bulk request ID (response.id). -
BulkJobStatushas a newCANCELLEDmember. A cancelled bulk request used to fail to parse.FAILEDis kept for compatibility. -
bounces.get_delivery_stats()raised because of theAllentry. -
stats.platform_usage(),stats.browser_platform_usage()andstats.click_location()raised on any day where a category had no activity. Postmark leaves out zero counts; they now read as0. -
templates.push()rejected integer server IDs.
| 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) |
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.
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.