Skip to content

Stats

Jump to bottom
Greg Svoboda edited this page Mar 4, 2026 · 1 revision

Stats

Statistics retrieval is done through ServerClient. You will need a server API token.

import postmark

client = postmark.ServerClient("your-server-token")

All stat methods support optional from_date, to_date, tag, and message_stream filters.

Outbound Overview

Get a high-level summary of all outbound activity.

import asyncio
from datetime import date

async def main():
    result = await client.stats.overview(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )

    print(f"Sent:            {result.sent}")
    print(f"Bounced:         {result.bounced}")
    print(f"Bounce rate:     {result.bounce_rate:.2%}")
    print(f"Spam complaints: {result.spam_complaints}")
    print(f"Opens:           {result.opens}")
    print(f"Unique opens:    {result.unique_opens}")
    print(f"Total clicks:    {result.total_clicks}")

asyncio.run(main())

Sent Counts

Daily breakdown of sent message counts.

from datetime import date

async def main():
    result = await client.stats.sent_counts(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )

    print(f"Total sent: {result.sent}")
    for day in result.days:
        print(f"  {day.date}:  {day.sent} sent")

Bounce Counts

Daily breakdown of bounces by type.

from datetime import date

async def main():
    result = await client.stats.bounce_counts(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )

    print(f"Hard bounces:  {result.hard_bounce}")
    print(f"Soft bounces:  {result.soft_bounce}")
    for day in result.days:
        print(f"  {day.date}:  hard={day.hard_bounce}  soft={day.soft_bounce}")

Spam Complaints

async def main():
    result = await client.stats.spam_counts(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    print(f"Spam complaints: {result.spam_complaints}")

Tracked Email Counts

async def main():
    result = await client.stats.tracked_counts(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    print(f"Tracked: {result.tracked}")

Email Opens

async def main():
    result = await client.stats.open_counts(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    print(f"Opens: {result.opens}  Unique: {result.unique_opens}")
    for day in result.days:
        print(f"  {day.date}:  opens={day.opens}  unique={day.unique_opens}")

Platform Usage

Device/platform breakdown for opens (desktop, mobile, webmail).

async def main():
    result = await client.stats.platform_usage(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    print(f"Desktop: {result.desktop}")
    print(f"Mobile:  {result.mobile}")
    print(f"Webmail: {result.webmail}")

Email Client Usage

async def main():
    result = await client.stats.email_client_usage(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    for client_entry in result.days:
        print(f"  {client_entry.date}")

Read Times

async def main():
    result = await client.stats.read_times(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    for entry in result.read_times:
        print(f"  {entry.within_seconds}s: {entry.count}")

Click Counts

async def main():
    result = await client.stats.click_counts(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    print(f"Clicks: {result.clicks}  Unique: {result.unique_clicks}")

Browser Usage

async def main():
    result = await client.stats.browser_usage(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    for browser in result.browser_families:
        print(f"  {browser.name}: {browser.count}")

Browser Platform Clicks

async def main():
    result = await client.stats.browser_platform_usage(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    print(f"Desktop: {result.desktop}")
    print(f"Mobile:  {result.mobile}")

Click Location

async def main():
    result = await client.stats.click_location(
        from_date=date(2024, 1, 1),
        to_date=date(2024, 1, 31),
    )
    for entry in result.click_locations:
        print(f"  {entry.location}: {entry.count}")

Further Reading

Clone this wiki locally