Class: ModMailService

models.ModMailService

Class providing the methods for working with Mod Mail

Table of contents

Properties

• notificationSubjectPrefix

Methods

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

Properties

notificationSubjectPrefix

• Readonly notificationSubjectPrefix: "[notification]"

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.

If you plan to send a message to the app-account or a moderator of the subreddit, use ModMailService.createModDiscussionConversation, ModMailService.createModInboxConversation, or ModMailService.createModNotification instead. Otherwise, messages sent to the app-account or moderator will automatically be routed to Mod Discussions.

Example

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

---

createModDiscussionConversation

▸ createModDiscussionConversation(params): Promise<string>

Creates a conversation in Mod Discussions with the moderators of the given subredditId.

Note: The app must be installed in the subreddit in order to create a conversation in Mod Discussions.

Parameters

Name	Type
params	Object
params.bodyMarkdown	string
params.subject	string
params.subredditId	string

Returns

Promise<string>

A Promise that resolves a string representing the conversationId of the message.

Example

const conversationId = await reddit.modMail.createModDiscussionConversation({
  subject: 'Test conversation',
  bodyMarkdown: '**Hello there** \n\n _Have a great day!_',
  subredditId: context.subredditId,
});

---

createModInboxConversation

▸ createModInboxConversation(params): Promise<string>

Creates a conversation in the Modmail Inbox with the moderators of the given subredditId.

Parameters

Name	Type
params	Object
params.bodyMarkdown	string
params.subject	string
params.subredditId	string

Returns

Promise<string>

A Promise that resolves a string representing the conversationId of the message.

Example

const conversationId = await reddit.modMail.createModInboxConversation({
  subject: 'Test conversation',
  bodyMarkdown: '**Hello there** \n\n _Have a great day!_',
  subredditId: context.subredditId,
});

---

createModNotification

▸ createModNotification(params): Promise<string>

Creates a notification in the Modmail Inbox. This function is different from ModMailService.createModInboxConversation in that the conversation also appears in the "Notifications" section of Modmail.

Parameters

Name	Type
params	Object
params.bodyMarkdown	string
params.subject	string
params.subredditId	string

Returns

Promise<string>

A Promise that resolves a string representing the conversationId of the message.

Example

const conversationId = await reddit.modMail.createModNotification({
  subject: 'Test notification',
  bodyMarkdown: '**Hello there** \n\n _This is a notification!_',
  subredditId: context.subredditId,
});

---

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	72 | 168 | 672	For how many hours the conversation needs to be muted. Must be one of 72, 168, or 672 hours

Returns

Promise<ConversationResponse & WithUserData>

Example

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

---

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']);