Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Modmail

class praw.models.reddit.subreddit.Modmail(subreddit: praw.models.Subreddit)

  Provides modmail functions for a `Subreddit`.

  For example, to send a new modmail from r/test to u/spez with the subject `"test"` along with a message body of `"hello"`:

      reddit.subreddit("test").modmail.create(subject="test", body="hello", recipient="spez")

  __call__(id: Optional[str] = None, mark_read: bool = False)

    Return an individual conversation.

    Parameters:

      - id – A reddit base36 conversation ID, e.g., `"2gmz"`.

      - mark_read – If `True`, conversation is marked as read (default: `False`).

    For example:

        reddit.subreddit("test").modmail("2gmz", mark_read=True)

    To print all messages from a conversation as Markdown source:

        conversation = reddit.subreddit("test").modmail("2gmz", mark_read=True)
        for message in conversation.messages:
            print(message.body_markdown)

    `ModmailConversation.user` is a special instance of `Redditor` with extra attributes describing the non-moderator user’s recent posts, comments, and modmail messages within the subreddit, as well as information on active bans and mutes. This attribute does not exist on internal moderator discussions.

    For example, to print the user’s ban status:

        conversation = reddit.subreddit("test").modmail("2gmz", mark_read=True)
        print(conversation.user.ban_status)

    To print a list of recent submissions by the user:

        conversation = reddit.subreddit("test").modmail("2gmz", mark_read=True)
        print(conversation.user.recent_posts)

  __init__(subreddit: praw.models.Subreddit)

    Initialize a `Modmail` instance.

  bulk_read(*, other_subreddits: Optional[List[Union[str, praw.models.Subreddit]]] = None, state: Optional[str] = None) → List[ModmailConversation]

    Mark conversations for subreddit(s) as read.

    Note

    Due to server-side restrictions, r/all is not a valid subreddit for this method. Instead, use `subreddits()` to get a list of subreddits using the new modmail.

    Parameters:

      - other_subreddits – A list of `Subreddit` instances for which to mark conversations (default: `None`).

      - state – Can be one of: `"all"`, `"archived"`, or `"highlighted"`, `"inprogress"`, `"join_requests"`, `"mod"`, `"new"`, `"notifications"`, or `"appeals"` (default: `"all"`). `"all"` does not include internal, archived, or appeals conversations.

    Returns:

      A list of `ModmailConversation` instances that were marked read.

    For example, to mark all notifications for a subreddit as read:

        subreddit = reddit.subreddit("test")
        subreddit.modmail.bulk_read(state="notifications")

  conversations(*, after: Optional[str] = None, other_subreddits: Optional[List[praw.models.Subreddit]] = None, sort: Optional[str] = None, state: Optional[str] = None, **generator_kwargs) → Iterator[ModmailConversation]

    Generate `ModmailConversation` objects for subreddit(s).

    Parameters:

      - after –

        A base36 modmail conversation id. When provided, the listing begins after this conversation (default: `None`).

        Deprecated since version 7.4.0: This parameter is deprecated and will be removed in PRAW 8.0. This method will automatically fetch the next batch. Please pass it in the `params` argument like so:

            for convo in subreddit.modmail.conversations(params={"after": "qovbn"}):
                # process conversation
                ...

      - other_subreddits – A list of `Subreddit` instances for which to fetch conversations (default: `None`).

      - sort – Can be one of: `"mod"`, `"recent"`, `"unread"`, or `"user"` (default: `"recent"`).

      - state – Can be one of: `"all"`, `"archived"`, `"highlighted"`, `"inprogress"`, `"join_requests"`, `"mod"`, `"new"`, `"notifications"`, or `"appeals"` (default: `"all"`). `"all"` does not include internal, archived, or appeals conversations.

    Additional keyword arguments are passed in the initialization of `ListingGenerator`.

    For example:

        conversations = reddit.subreddit("all").modmail.conversations(state="mod")

  create(*, author_hidden: bool = False, body: str, recipient: Union[str, praw.models.Redditor], subject: str) → ModmailConversation

    Create a new `ModmailConversation`.

    Parameters:

      - author_hidden – When `True`, author is hidden from non-moderators (default: `False`).

      - body – The message body. Cannot be empty.

      - recipient – The recipient; a username or an instance of `Redditor`.

      - subject – The message subject. Cannot be empty.

    Returns:

      A `ModmailConversation` object for the newly created conversation.

        subreddit = reddit.subreddit("test")
        redditor = reddit.redditor("bboe")
        subreddit.modmail.create(subject="Subject", body="Body", recipient=redditor)

  subreddits() → Generator[praw.models.Subreddit, None, None]

    Yield subreddits using the new modmail that the user moderates.

    For example:

        subreddits = reddit.subreddit("all").modmail.subreddits()

  unread_count() → Dict[str, int]

    Return unread conversation count by conversation state.

    At time of writing, possible states are: `"archived"`, `"highlighted"`, `"inprogress"`, `"join_requests"`, `"mod"`, `"new"`, `"notifications"`, or `"appeals"`.

    Returns:

      A dict mapping conversation states to unread counts.

    For example, to print the count of unread moderator discussions:

        subreddit = reddit.subreddit("test")
        unread_counts = subreddit.modmail.unread_count()
        print(unread_counts["mod"])