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

This module provides a `aioxmpp.tracking` service which tracks XEP-0184 replies to messages and accordinly 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 reciept 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`