Bounces

Bounces

Bounce management is done through ServerClient. You will need a server API token.

import postmark

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

Delivery Statistics

Retrieve a summary of bounce counts across all bounce types.

import asyncio

async def main():
    stats = await client.bounces.get_delivery_stats()

    print(f"Inactive addresses: {stats.inactive_mails}")
    for entry in stats.bounces:
        print(f"  {entry.name}: {entry.count}")

asyncio.run(main())

List Bounces

Fetch a paginated list of bounces. Filter by bounce type using the BounceType enum.

import asyncio
from postmark.models.bounces import BounceType

async def main():
    # List all bounces
    result = await client.bounces.list()
    print(f"{result.total} total bounces, showing {len(result.items)}")

    for b in result.items:
        print(f"  [{b.id}] {b.email}  bounced={b.bounced_at:%Y-%m-%d}  inactive={b.inactive}")

    # Filter to hard bounces only
    result = await client.bounces.list(
        bounce_type=BounceType.HARD_BOUNCE,
        count=50,
        offset=0,
    )

asyncio.run(main())

Available BounceType values include: HARD_BOUNCE, SOFT_BOUNCE, TRANSIENT, SUBSCRIBE, UNSUBSCRIBE, MANUAL_SUPPRESSION, SPAM_COMPLAINT, and more.

Get a Single Bounce

Retrieve the details of a specific bounce by its ID.

async def main():
    bounce = await client.bounces.get(bounce_id=692560173)

    print(f"Email:      {bounce.email}")
    print(f"Type:       {bounce.type}")
    print(f"Inactive:   {bounce.inactive}")
    print(f"Can activate: {bounce.can_activate}")
    print(f"Bounced at: {bounce.bounced_at}")

Get Bounce Dump

Retrieve the full raw email content for a bounced message.

async def main():
    dump = await client.bounces.get_dump(bounce_id=692560173)
    print(dump.body)

Activate a Bounce

Re-enable sending to a previously bounced address. Check can_activate before calling this.

async def main():
    result = await client.bounces.activate(bounce_id=692560173)

    print(f"Message:  {result.message}")
    print(f"Inactive: {result.bounce.inactive}")

Stream All Bounces

Use the async generator to auto-paginate through all bounces.

async def main():
    async for bounce in client.bounces.stream():
        print(f"  {bounce.email}")

Further Reading

• Error Handling
• Postmark Bounces API