# `mdr` — Message Delivery Reciepts (XEP-0184)

This module provides a `aioxmpp.tracking` service which tracks XEP-0184 replies to messages and accordingly updates attached `MessageTracker` objects.

New in version 0.10.

To make use of receipt tracking, `summon()` the `DeliveryReceiptsService` on your `aioxmpp.Client` and use the `attach_tracker()` method.

To send delivery receipts, the `aioxmpp.mdr.compose_receipt()` helper function is provided.

class aioxmpp.DeliveryReceiptsService(client, **kwargs)

  Tracking Service which tracks XEP-0184 replies.

  To send a tracked message, use the `attach_tracker()` method before sending.

  attach_tracker(stanza, tracker=None)

    Return a new tracker or modify one to track the stanza.

    Parameters:

      - stanza (`aioxmpp.Message`) – Stanza to track.

      - tracker (`tracking.MessageTracker`) – Existing tracker to attach to.

    Raises:

      - ValueError – if the stanza is of type `ERROR`

      - ValueError – if the stanza contains a delivery receipt

    Returns:

      The message tracker for the stanza.

    Return type:

      `tracking.MessageTracker`

    The stanza gets a XEP-0184 receipt request attached and internal handlers are set up to update the tracker state once a confirmation is received.

    Warning

    See the General Remarks about Tracking and Memory Consumption.

aioxmpp.mdr.compose_receipt(message)

  Compose a XEP-0184 delivery receipt for a `Message`.

  Parameters:

    message (`Message`) – The message to compose the receipt for.

  Raises:

    - ValueError – if the input message is of type `ERROR`

    - ValueError – if the input message is a message receipt itself

  Returns:

    A message which serves as a receipt for the input message.

  Return type:

    `Message`