# Delay Policy (/sdks/python/how-to/queues/delay-policy)



<Callout type="info" title="Which to use">
  For the task-oriented how-to, see [Delayed Messages](./delayed-messages). This page focuses on the `delay_in_seconds` delay-policy field itself — its evaluation point and interaction with redelivery.
</Callout>

## Overview [#overview]

`delay_in_seconds` is the field on `QueueMessage` that defers when a queued message becomes visible to consumers — set it before sending, and the broker excludes the message from delivery until the countdown expires. It starts the moment the broker accepts the message, not when the client sends it, and is evaluated once, at send time.

**Gotchas:** the delay is a floor, not a guarantee — the message becomes *eligible* when the timer expires, but actual delivery still waits for a consumer to poll, so don't rely on it for precise scheduling. It's one-shot: there's no recurrence or cron-like behavior, so long or repeating delays need application logic on top. And it's independent of redelivery — a delayed message that's later nacked or times out after delivery follows normal visibility-timeout/retry rules, not the original send-time delay.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* Python SDK installed (`pip install kubemq`)

## Code [#code]

```python title="delay_policy.py"
"""Example: Delay policy — send a message with a delivery delay."""

from __future__ import annotations

import asyncio

from kubemq import AsyncQueuesClient
from kubemq import QueueMessage


async def main() -> None:
    async with AsyncQueuesClient(
        address="localhost:50000",
        client_id="python-queues-stream-delay-policy-client",
    ) as client:
        # Send a message with a 5-second delay
        result = await client.send_queue_message(
            QueueMessage(
                channel="python-queues-stream.delay-policy",
                body=b"delayed message",
                delay_in_seconds=5,
            )
        )
        print(f"Sent message with 5s delay: {result}")

        # Try to receive immediately — should get nothing
        response = await client.receive_queue_messages(
            channel="python-queues-stream.delay-policy",
            max_messages=1,
            wait_timeout_seconds=1,
            auto_ack=True,
        )
        print(f"Immediate: {len(response.messages)} messages (expected 0)")

        # Wait for the delay to expire
        print("Waiting 6 seconds for delay...")
        await asyncio.sleep(6)

        # Now the message should be available
        response = await client.receive_queue_messages(
            channel="python-queues-stream.delay-policy",
            max_messages=1,
            wait_timeout_seconds=5,
            auto_ack=True,
        )
        print(f"After delay: {len(response.messages)} messages (expected 1)")
        for msg in response.messages:
            print(f"  Received: {msg.body.decode('utf-8')}")


if __name__ == "__main__":
    asyncio.run(main())

```

## How It Works [#how-it-works]

* `QueueMessage.delay_in_seconds=5` instructs the broker to hold the message for 5 seconds before making it visible to consumers.
* The first poll with `wait_timeout_seconds=1` returns zero messages, confirming the delay is in effect.
* After a 6-second sleep the delay window has elapsed; the second poll successfully retrieves the delayed message with `auto_ack=True`.
* Delay policy applies to individual messages at send time; it is independent of channel-level configuration.

## Related [#related]

* [Delayed Messages](./delayed-messages) — task-oriented walkthrough for sending delayed messages
* [Pattern overview](/learn/queues/getting-started)
* [Python SDK Reference](/sdks/python/reference/queues)
* [Send & Receive](/sdks/python/tutorials/send-receive)
* [Ack All](/sdks/python/how-to/queues/ack-all)