# Private messages

## List Private Messages

`TOOL discourse_list_private_messages`

List authenticated personal or group private-message mailboxes. Returns normalized JSON messages and pagination metadata.

Authentication: no security requirement declared for this operation.

Parameters:

- `username` (argument, string, optional)
  Type: string

- `mailbox` (argument, string, optional)
  Type: string
  
  enum: ["inbox","sent","archive","unread","new"]

- `group_name` (argument, string, optional)
  Type: string

- `page` (argument, integer, optional)
  Type: integer
  
  minimum: 0

- `per_page` (argument, integer, optional)
  Type: integer
  
  minimum: 1
  
  maximum: 100

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_list_private_messages",
    "arguments": {
        "username": "string",
        "mailbox": "inbox",
        "group_name": "string",
        "page": 0,
        "per_page": 1
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_list_private_messages",
  "arguments": {
    "username": "string",
    "mailbox": "inbox",
    "group_name": "string",
    "page": 0,
    "per_page": 1
  }
});
```

### Python

```python
result = await session.call_tool("discourse_list_private_messages", arguments={
  "username": "string",
  "mailbox": "inbox",
  "group_name": "string",
  "page": 0,
  "per_page": 1
})
```


## Read Private Message

`TOOL discourse_read_private_message`

Read an authenticated private message, its posts, and direct allowed-user and allowed-group records. Rejects public topics.

Authentication: no security requirement declared for this operation.

Parameters:

- `topic_id` (argument, integer, required)
  Type: integer
  
  exclusiveMinimum: 0

- `post_limit` (argument, integer, optional) - Max posts to return (default 5, max 50)
  Type: integer
  
  Max posts to return (default 5, max 50)
  
  minimum: 1
  
  maximum: 50

- `start_post_number` (argument, integer, optional) - Start from this post number (1-based)
  Type: integer
  
  Start from this post number (1-based)
  
  minimum: 1

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_read_private_message",
    "arguments": {
        "topic_id": 0,
        "post_limit": 1,
        "start_post_number": 1
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_read_private_message",
  "arguments": {
    "topic_id": 0,
    "post_limit": 1,
    "start_post_number": 1
  }
});
```

### Python

```python
result = await session.call_tool("discourse_read_private_message", arguments={
  "topic_id": 0,
  "post_limit": 1,
  "start_post_number": 1
})
```


## Create Private Message

`TOOL discourse_create_private_message`

Create a private message for typed user, group, or email recipients. Unknown emails may create staged users. author_username requires a global API key; the response reports actual attribution.

Authentication: no security requirement declared for this operation.

Parameters:

- `title` (argument, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 300

- `raw` (argument, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 30000

- `usernames` (argument, Array<string>, optional)
  Type: Array<string>
  
  Items:
    Type: string

- `group_names` (argument, Array<string>, optional)
  Type: Array<string>
  
  Items:
    Type: string

- `email_addresses` (argument, Array<string>, optional)
  Type: Array<string>
  
  Items:
    Type: string

- `author_username` (argument, string, optional)
  Type: string

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_create_private_message",
    "arguments": {
        "title": "string",
        "raw": "string",
        "usernames": [
          "string"
        ],
        "group_names": [
          "string"
        ],
        "email_addresses": [
          "string"
        ],
        "author_username": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_create_private_message",
  "arguments": {
    "title": "string",
    "raw": "string",
    "usernames": [
      "string"
    ],
    "group_names": [
      "string"
    ],
    "email_addresses": [
      "string"
    ],
    "author_username": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_create_private_message", arguments={
  "title": "string",
  "raw": "string",
  "usernames": [
    "string"
  ],
  "group_names": [
    "string"
  ],
  "email_addresses": [
    "string"
  ],
  "author_username": "string"
})
```


## Reply to Private Message

`TOOL discourse_reply_private_message`

Safely reply to an existing private message after verifying its archetype. author_username requires a global API key; the response reports actual attribution.

Authentication: no security requirement declared for this operation.

Parameters:

- `topic_id` (argument, integer, required)
  Type: integer
  
  exclusiveMinimum: 0

- `raw` (argument, string, required)
  Type: string
  
  minLength: 1
  
  maxLength: 30000

- `reply_to_post_number` (argument, integer, optional)
  Type: integer
  
  exclusiveMinimum: 0

- `author_username` (argument, string, optional)
  Type: string

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_reply_private_message",
    "arguments": {
        "topic_id": 0,
        "raw": "string",
        "reply_to_post_number": 0,
        "author_username": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_reply_private_message",
  "arguments": {
    "topic_id": 0,
    "raw": "string",
    "reply_to_post_number": 0,
    "author_username": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_reply_private_message", arguments={
  "topic_id": 0,
  "raw": "string",
  "reply_to_post_number": 0,
  "author_username": "string"
})
```


## Invite to Private Message

`TOOL discourse_invite_to_private_message`

Add a user or group to a private message, or submit an opaque email invitation. Email success does not confirm delivery or participant access. author_username requires a global API key.

Authentication: no security requirement declared for this operation.

Parameters:

- `topic_id` (argument, integer, required)
  Type: integer
  
  exclusiveMinimum: 0

- `username` (argument, string, optional)
  Type: string

- `group_name` (argument, string, optional)
  Type: string

- `email_address` (argument, string, optional)
  Type: string

- `notify_group_members` (argument, boolean, optional)
  Type: boolean

- `custom_message` (argument, string, optional)
  Type: string
  
  minLength: 1
  
  maxLength: 3000

- `author_username` (argument, string, optional)
  Type: string

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_invite_to_private_message",
    "arguments": {
        "topic_id": 0,
        "username": "string",
        "group_name": "string",
        "email_address": "string",
        "notify_group_members": true,
        "custom_message": "string",
        "author_username": "string"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_invite_to_private_message",
  "arguments": {
    "topic_id": 0,
    "username": "string",
    "group_name": "string",
    "email_address": "string",
    "notify_group_members": true,
    "custom_message": "string",
    "author_username": "string"
  }
});
```

### Python

```python
result = await session.call_tool("discourse_invite_to_private_message", arguments={
  "topic_id": 0,
  "username": "string",
  "group_name": "string",
  "email_address": "string",
  "notify_group_members": true,
  "custom_message": "string",
  "author_username": "string"
})
```