Class: ModMailService

models.ModMailService

Class providing the methods for working with Mod Mail

Table of contents

Methods

• approveConversation
• archiveConversation
• bulkReadConversations
• createConversation
• disapproveConversation
• getConversation
• getConversations
• getSubreddits
• getUnreadCount
• getUserConversations
• highlightConversation
• muteConversation
• readConversations
• reply
• tempBanConversation
• unarchiveConversation
• unbanConversation
• unhighlightConversation
• unmuteConversation
• unreadConversations

Methods

approveConversation

▸ approveConversation(conversationId): Promise<ConversationResponse & WithUserData>

Approve the non mod user associated with a particular conversation.

Parameters

Name	Type	Description
conversationId	string	Id of a modmail conversation

Returns

Promise<ConversationResponse & WithUserData>

Example

await reddit.modMail.approveConversation('abcdef');

---

archiveConversation

▸ archiveConversation(conversationId): Promise<ConversationResponse>

Marks a conversation as archived

Parameters

Name	Type	Description
conversationId	string	Id of a modmail conversation

Returns

Promise<ConversationResponse>

Example

await reddit.modMail.archive('abcdef');

---

bulkReadConversations

▸ bulkReadConversations(subreddits, state): Promise<string[]>

Marks all conversations read for a particular conversation state within the passed list of subreddits.

Parameters

Name	Type	Description
subreddits	string[]	Array of subreddit names
state	ConversationStateFilter	One of the possible conversation states ('all' to read all conversations)

Returns

Promise<string[]>

conversationIds

Example

const conversationIds = await reddit.modMail.bulkReadConversations(
  ['askReddit', 'myAwesomeSubreddit'],
  'filtered'
);

---

createConversation

▸ createConversation(params): Promise<ConversationResponse & WithUserData>

Creates a new conversation for a particular SR.

This endpoint will create a ModmailConversation object as well as the first ModmailMessage within the ModmailConversation object.

Parameters

Name	Type	Description
params	Object	-
params.body	string	markdown text
params.isAuthorHidden?	boolean	is author hidden? (default: false)
params.subject	string	subject of the conversation. max 100 characters
params.subredditName	string	subreddit name
params.to?	null | string	a user (e.g. u/username), a subreddit (e.g. r/subreddit) or null

Returns

Promise<ConversationResponse & WithUserData>

Note

Note on {param.to}: The to field for this endpoint is somewhat confusing. It can be:

• A User, passed like "username" or "u/username"
• A Subreddit, passed like "r/subreddit"
• null, meaning an internal moderator discussion

In this way to is a bit of a misnomer in modmail conversations. What it really means is the participant of the conversation who is not a mod of the subreddit.

Example

const { conversation, messages, modActions } = await reddit.modMail.createConversation({
  subredditName: 'askReddit',
  subject: 'Test conversation',
  body: 'Lorem ipsum sit amet',
  to: null,
});

---

disapproveConversation

▸ disapproveConversation(conversationId): Promise<ConversationResponse & WithUserData>

Disapprove the non mod user associated with a particular conversation.

Parameters

Name	Type	Description
conversationId	string	Id of a modmail conversation

Returns

Promise<ConversationResponse & WithUserData>

Example

await reddit.modMail.disapproveConversation('abcdef');

---

getConversation

▸ getConversation(params): Promise<GetConversationResponse>

Returns all messages, mod actions and conversation metadata for a given conversation id

Parameters

Name	Type	Description
params	Object	-
params.conversationId	string	a modmail conversation id
params.markRead?	boolean	mark read?

Returns

Promise<GetConversationResponse>

Example

const { conversation, messages, modActions, user } = await reddit.modMail.getConversation({
  conversationId: 'abcdef',
  markRead: true,
});

---

getConversations

▸ getConversations(params): Promise<GetConversationsResponse>

Get conversations for a logged in user or subreddits

Parameters

Name	Type
params	GetConversationsRequest

Returns

Promise<GetConversationsResponse>

Example

const { viewerId, conversations } = await reddit.modMail.getConversations({
  after: 'abcdef',
  limit: 42,
});

const arrayOfConversations = Object.values(conversations);

---

getSubreddits

▸ getSubreddits(): Promise<{ [key: string]: SubredditData; }>

Returns a list of Subreddits that the user moderates with mail permission

Returns

Promise<{ [key: string]: SubredditData; }>

Example

const subredditsData = await reddit.modMail.getSubreddits();

for (const subreddit of Object.values(subreddits)) {
  console.log(subreddit.id);
  console.log(subreddit.name);
}

---

getUnreadCount

▸ getUnreadCount(): Promise<UnreadCountResponse>

Endpoint to retrieve the unread conversation count by conversation state.

Returns

Promise<UnreadCountResponse>

Example

const response = await reddit.modMail.getUnreadCount();

console.log(response.highlighted);
console.log(response.new);

---

getUserConversations

▸ getUserConversations(conversationId): Promise<ConversationUserData>

Returns recent posts, comments and modmail conversations for a given user.

Parameters

Name	Type	Description
conversationId	string	Id of a modmail conversation

Returns

Promise<ConversationUserData>

Example

const data = await reddit.modMail.getUserConversations('abcdef');

console.log(data.recentComments);
console.log(data.recentPosts);

---

highlightConversation

▸ highlightConversation(conversationId): Promise<ConversationResponse>

Marks a conversation as highlighted.

Parameters

Name	Type	Description
conversationId	string	Id of a modmail conversation

Returns

Promise<ConversationResponse>

Example

await reddit.modMail.highlightConversation('abcdef');

---

muteConversation

▸ muteConversation(params): Promise<ConversationResponse & WithUserData>

Marks a conversation as read for the user.

Parameters

Name	Type	Description
params	Object	-
params.conversationId	string	Id of a modmail conversation
params.numHours	number	For how many hous the conversation needs to be muted

Returns

Promise<ConversationResponse & WithUserData>

Example

await reddit.modMail.muteConversation({ conversationId: 'abcdef', numHours: 2 });

---

readConversations

▸ readConversations(conversationIds): Promise<void>

Marks a conversations as read for the user.

Parameters

Name	Type	Description
conversationIds	string[]	An array of ids

Returns

Promise<void>

Example

await reddit.modMail.readConversations(['abcdef', 'qwerty']);

---

reply

▸ reply(params): Promise<ConversationResponse & WithUserData>

Creates a new message for a particular conversation.

Parameters

Name	Type	Description
params	Object	-
params.body	string	markdown text
params.conversationId	string	Id of a modmail conversation
params.isAuthorHidden?	boolean	is author hidden? (default: false)
params.isInternal?	boolean	is internal message? (default: false)

Returns

Promise<ConversationResponse & WithUserData>

Example

await reddit.modMail.reply({
  body: 'Lorem ipsum sit amet',
  conversationId: 'abcdef',
});

---

tempBanConversation

▸ tempBanConversation(params): Promise<ConversationResponse & WithUserData>

Temporary ban (switch from permanent to temporary ban) the non mod user associated with a particular conversation.

Parameters

Name	Type	Description
params	Object	-
params.conversationId	string	a modmail conversation id
params.duration	number	duration in days, max 999

Returns

Promise<ConversationResponse & WithUserData>

Example

await reddit.modMail.tempBanConversation({ conversationId: 'abcdef', duration: 42 });

---

unarchiveConversation

▸ unarchiveConversation(conversationId): Promise<ConversationResponse>

Marks conversation as unarchived.

Parameters

Name	Type	Description
conversationId	string	Id of a modmail conversation

Returns

Promise<ConversationResponse>

Example

await reddit.modMail.unarchiveConversation('abcdef');

---

unbanConversation

▸ unbanConversation(conversationId): Promise<ConversationResponse & WithUserData>

Unban the non mod user associated with a particular conversation.

Parameters

Name	Type	Description
conversationId	string	a modmail conversation id

Returns

Promise<ConversationResponse & WithUserData>

Example

await reddit.modMail.unbanConversation('abcdef');

---

unhighlightConversation

▸ unhighlightConversation(conversationId): Promise<ConversationResponse>

Removes a highlight from a conversation.

Parameters

Name	Type	Description
conversationId	string	Id of a modmail conversation

Returns

Promise<ConversationResponse>

Example

await reddit.modMail.unhighlightConversation('abcdef');

---

unmuteConversation

▸ unmuteConversation(conversationId): Promise<ConversationResponse & WithUserData>

Unmutes the non mod user associated with a particular conversation.

Parameters

Name	Type	Description
conversationId	string	Id of a modmail conversation

Returns

Promise<ConversationResponse & WithUserData>

Example

await reddit.modMail.unmuteConversation('abcdef');

---

unreadConversations

▸ unreadConversations(conversationIds): Promise<void>

Marks conversations as unread for the user.

Parameters

Name	Type	Description
conversationIds	string[]	An array of ids

Returns

Promise<void>

Example

await reddit.modMail.unreadConversations(['abcdef', 'qwerty']);