Azure Service Bus: Dead-Lettering

from azure.servicebus import ServiceBusClient, ServiceBusMessage, ServiceBusSubQueue

CONN_STR = "Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

with ServiceBusClient.from_connection_string(CONN_STR) as client:
    with client.get_queue_sender("orders") as sender:
        sender.send_messages(ServiceBusMessage("order-negative-total"))

    with client.get_queue_receiver("orders", max_wait_time=5) as receiver:
        for msg in receiver.receive_messages(max_message_count=1, max_wait_time=5):
            receiver.dead_letter_message(
                msg,
                reason="validation-failed",
                error_description="total was negative",
            )

    with client.get_queue_receiver(
        "orders", sub_queue=ServiceBusSubQueue.DEAD_LETTER, max_wait_time=5
    ) as dlq_receiver:
        for msg in dlq_receiver.receive_messages(max_message_count=1, max_wait_time=5):
            print("reason:", msg.dead_letter_reason)
            print("description:", msg.dead_letter_error_description)
            dlq_receiver.complete_message(msg)

$ docker run --rm --network container:az-sb-emu-15 -v "$(pwd)":/app -w /app python:3.14-slim bash -c "pip install -q azure-servicebus==7.15.0 2>&1 | tail -1 && python sb_dlq_description.py"
[notice] To update, run: pip install --upgrade pip
reason: validation-failed
description: total was negative

Both strings round-trip onto the DLQ message exactly as passed — error_description is a free-form detail alongside the shorter, more categorical reason, and neither is interpreted by Service Bus itself; they’re there purely for whatever reads the DLQ afterward.

from azure.servicebus import ServiceBusClient, ServiceBusMessage, ServiceBusSubQueue

CONN_STR = "Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

with ServiceBusClient.from_connection_string(CONN_STR) as client:
    with client.get_queue_sender("orders") as sender:
        sender.send_messages(ServiceBusMessage("order-to-drain"))
    with client.get_queue_receiver("orders", max_wait_time=5) as receiver:
        for msg in receiver.receive_messages(max_message_count=1, max_wait_time=5):
            receiver.dead_letter_message(msg, reason="draining-practice")

    with client.get_queue_receiver(
        "orders", sub_queue=ServiceBusSubQueue.DEAD_LETTER, max_wait_time=5
    ) as dlq_receiver:
        first_pass = dlq_receiver.receive_messages(max_message_count=5, max_wait_time=5)
        print("DLQ messages before drain:", len(first_pass))
        for msg in first_pass:
            dlq_receiver.complete_message(msg)

    with client.get_queue_receiver(
        "orders", sub_queue=ServiceBusSubQueue.DEAD_LETTER, max_wait_time=5
    ) as dlq_receiver:
        second_pass = dlq_receiver.receive_messages(max_message_count=5, max_wait_time=5)
        print("DLQ messages after drain:", len(second_pass))

$ docker run --rm --network container:az-sb-emu-15 -v "$(pwd)":/app -w /app python:3.14-slim bash -c "pip install -q azure-servicebus==7.15.0 2>&1 | tail -1 && python sb_dlq_drain.py"
[notice] To update, run: pip install --upgrade pip
DLQ messages before drain: 1
DLQ messages after drain: 0

Completing a DLQ message removes it from the DLQ the same way completing a main-queue message removes it from there — permanently, not just marking it read. The second read comes back empty because there’s nothing left to hand out, not because anything is being hidden from a receiver that already saw it once.

from azure.servicebus import ServiceBusClient, ServiceBusMessage, ServiceBusSubQueue

CONN_STR = "Endpoint=sb://localhost;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=SAS_KEY_VALUE;UseDevelopmentEmulator=true;"

with ServiceBusClient.from_connection_string(CONN_STR) as client:
    with client.get_queue_sender("orders") as sender:
        sender.send_messages(ServiceBusMessage("order-poison"))

    # Config.json sets MaxDeliveryCount to 3 — abandon it that many times, never completing it
    for attempt in range(3):
        with client.get_queue_receiver("orders", max_wait_time=5) as receiver:
            for m in receiver.receive_messages(max_message_count=1, max_wait_time=5):
                print(f"attempt {attempt}: delivery_count={m.delivery_count}")
                receiver.abandon_message(m)

    with client.get_queue_receiver(
        "orders", sub_queue=ServiceBusSubQueue.DEAD_LETTER, max_wait_time=5
    ) as dlq_receiver:
        for m in dlq_receiver.receive_messages(max_message_count=5, max_wait_time=5):
            print("auto-dead-lettered:", str(m), "reason:", m.dead_letter_reason)
            dlq_receiver.complete_message(m)

$ docker run --rm --network container:az-sb-emu-15 -v "$(pwd)":/app -w /app python:3.14-slim bash -c "pip install -q azure-servicebus==7.15.0 2>&1 | tail -1 && python sb_auto_dlq.py"
[notice] To update, run: pip install --upgrade pip
attempt 0: delivery_count=0
attempt 1: delivery_count=1
attempt 2: delivery_count=2
auto-dead-lettered: order-poison reason: MaxDeliveryCountExceeded

Nobody ever called dead_letter_message on this one — Service Bus itself moved it to the DLQ once its delivery count hit MaxDeliveryCount, and set dead_letter_reason to MaxDeliveryCountExceeded rather than whatever string application code would have passed. That reason string is exactly how code reading the DLQ later tells “the broker gave up on this” apart from “a consumer explicitly rejected this.”