# Paperless Post MCP tools

> Every Paperless Post MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/paperless-post

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

11 tools for Paperless Post on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own Paperless Post account (the host or a co-host of the event)
- Integration page: https://cotlet.dev/integrations/paperless-post-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `paperless-post_list_events` | read | Your Cards and Flyers from My Events, with type, date and send status. |
| `paperless-post_get_event` | read | Event details: title, host, date, time, location and the design type. |
| `paperless-post_list_guests` | read | The Tracking page: each guest or group with status, number attending and Guest Tags. |
| `paperless-post_get_guest` | read | One guest: status, number attending and the messages sent to them. |
| `paperless-post_export_guest_list` | read | The Tracking page as a CSV download link, with each guest's RSVP status. |
| `paperless-post_list_contacts` | read | Your Address Book: names, emails and phone numbers saved for reuse. |
| `paperless-post_add_guests` | write | Add guests to the unsent guest list of an event. Nothing is sent until send_invitation. |
| `paperless-post_send_invitation` | write | Send the Card or Flyer to everyone on the unsent list, now or at a set time. |
| `paperless-post_send_message` | write | Broadcast from Messages & Reminders to guests by status and Guest Tag. |
| `paperless-post_send_private_message` | write | Message one guest in their message log. |
| `paperless-post_tag_guests` | write | Add a Guest Tag to guests. Tags are visible to hosts and co-hosts only. |

## List events

MCP tool: `paperless-post_list_events`

Access: read.

Returns the Cards and Flyers on your account, newest first. Use the event_id of each item in the other endpoints. Drafts have no guests sent yet.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | enum | no | draft, sent or scheduled. Default: sent. |
| `limit` | integer | no | Number of events to return. Default: 20. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_list_events",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "events": [
      {
        "event_id": "ev_8F3K2Q",
        "title": "Summer Gala",
        "type": "card",
        "status": "sent",
        "event_date": "2026-10-17T19:00:00-04:00"
      },
      {
        "event_id": "ev_2M9X1B",
        "title": "Baby shower",
        "type": "flyer",
        "status": "draft",
        "event_date": "2026-11-08T14:00:00-05:00"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Get event

MCP tool: `paperless-post_get_event`

Access: read.

Returns what guests see on the invitation: title, host name, date and time, time zone and location. Use it before a time or location message so the text matches the invitation.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Card or Flyer ID from list_events. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_get_event",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8F3K2Q",
    "title": "Summer Gala",
    "type": "card",
    "host": "Dana Whitfield",
    "event_date": "2026-10-17T19:00:00-04:00",
    "location": "The Boathouse, 12 Pier Road",
    "status": "sent"
  },
  "isError": false
}
```

## List guests

MCP tool: `paperless-post_list_guests`

Access: read.

Returns the rows of the Tracking page for one event, with each guest's status, how many are attending and their Guest Tags. Guest Tags show only if you are a host or co-host. Pass guest_id to get_guest or tag_guests.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Card or Flyer ID from list_events. |
| `status` | string | no | Only guests with this status as shown on the Tracking page, for example attending. |
| `tag` | string | no | Only guests with this Guest Tag. |
| `search` | string | no | Match by name, email or phone. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_list_guests",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "guests": [
      {
        "guest_id": "g_20417",
        "name": "Maya Chen",
        "status": "attending",
        "total_attending": 2,
        "tags": []
      },
      {
        "guest_id": "g_20433",
        "name": "Jordan Reyes",
        "status": "opened",
        "total_attending": 0,
        "tags": []
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Get guest

MCP tool: `paperless-post_get_guest`

Access: read.

Returns one row of the Tracking page with the broadcast and private messages sent to that guest. Use it to check what a guest already received before you write again.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Card or Flyer ID from list_events. |
| `guest_id` | string | yes | Guest ID from list_guests. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_get_guest",
    "arguments": {
      "event_id": "event_8c41d2",
      "guest_id": "guest_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "guest_id": "g_20433",
    "name": "Jordan Reyes",
    "status": "opened",
    "total_attending": 0,
    "tags": [],
    "messages": [
      {
        "type": "broadcast",
        "subject": "Please RSVP by Friday",
        "sent_at": "2026-10-10T18:42:00-04:00"
      }
    ]
  },
  "isError": false
}
```

## Export guest list

MCP tool: `paperless-post_export_guest_list`

Access: read.

Returns a link to the CSV the Export guest list button on the Tracking page downloads. The link works for a limited time, so download it right away. Reads only; nothing changes in Paperless Post.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Card or Flyer ID from list_events. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_export_guest_list",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8F3K2Q",
    "rows": 41,
    "download_url": "https://files.cotlet.example/exports/ev_8F3K2Q-guests.csv"
  },
  "isError": false
}
```

## List contacts

MCP tool: `paperless-post_list_contacts`

Access: read.

Returns the contacts saved in your Address Book, so your agent can add known people to a guest list without a file. Matching by search is case insensitive.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string | no | Match by name, email or phone. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_list_contacts",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "contacts": [
      {
        "contact_id": "c_7731",
        "name": "Maya Chen",
        "email": "maya@example.com"
      },
      {
        "contact_id": "c_7740",
        "name": "Jordan Reyes",
        "email": "jordan@example.com"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Add guests

MCP tool: `paperless-post_add_guests`

Access: write.

Adds guests to the unsent list, the same list the spreadsheet upload fills. Each guest needs a name and an email or phone number. Nothing reaches the guests until send_invitation, and you remove a guest in the app, so this call needs no confirmation.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Card or Flyer ID from list_events. |
| `guests` | object[] | yes | List of { name, email or phone, group_name, total_invited }. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_add_guests",
    "arguments": {
      "event_id": "ev_8F3K2Q",
      "guests": [
        {
          "name": "Maya Chen",
          "email": "maya@example.com",
          "total_invited": 2
        },
        {
          "name": "Jordan Reyes",
          "email": "jordan@example.com",
          "group_name": "Reyes family"
        },
        {
          "name": "Ana Reyes",
          "phone": "+12125550188",
          "group_name": "Reyes family"
        }
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8F3K2Q",
    "added": 2,
    "unsent_list_total": 2,
    "status": "unsent"
  },
  "isError": false
}
```

## Send invitation

MCP tool: `paperless-post_send_invitation`

Access: write. Confirm: waits for the user's OK before it runs.

Sends the invitation to everyone on the unsent guest list. With send_at it is scheduled instead of sent now. Guests receive it as soon as it goes out. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Card or Flyer ID from list_events. |
| `send_at` | datetime | no | ISO 8601 with time zone. Empty: send now. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_send_invitation",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8F3K2Q",
    "status": "scheduled",
    "recipients": 41,
    "send_at": "2026-10-16T09:00:00-04:00"
  },
  "isError": false
}
```

## Send message

MCP tool: `paperless-post_send_message`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a broadcast like the Messages & Reminders screen: pick a template or write your own, then recipients by guest status and optional Guest Tags. The text is limited to 2,000 characters and cannot carry attachments. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Card or Flyer ID from list_events. |
| `template` | enum | no | reminder_to_rsvp, event_reminder, time_location_change or write_your_own. Default: write_your_own. |
| `message` | string | yes | Message text, up to 2,000 characters. No attachments. |
| `subject` | string | no | Email subject. |
| `statuses` | string[] | no | Guest statuses to reach, as shown on the Tracking page, for example attending. Default: all guests. |
| `tags` | string[] | no | Only guests with these Guest Tags. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_send_message",
    "arguments": {
      "event_id": "ev_8F3K2Q",
      "template": "reminder_to_rsvp",
      "subject": "Please RSVP by Friday",
      "message": "Hi! We are finalizing the headcount for the Summer Gala. Please reply by Friday.",
      "statuses": [
        "opened"
      ]
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8F3K2Q",
    "broadcast_id": "bc_51290",
    "status": "sent",
    "recipients": 23,
    "sent_at": "2026-10-10T18:42:00-04:00"
  },
  "isError": false
}
```

## Send private message

MCP tool: `paperless-post_send_private_message`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a private message to one guest, as the Private message option in Messages & Reminders does. The text is limited to 2,000 characters. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Card or Flyer ID from list_events. |
| `guest_id` | string | yes | Guest ID from list_guests. |
| `message` | string | yes | Message text, up to 2,000 characters. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_send_private_message",
    "arguments": {
      "event_id": "event_8c41d2",
      "guest_id": "guest_8c41d2",
      "message": "message"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8F3K2Q",
    "guest_id": "g_20433",
    "status": "sent",
    "sent_at": "2026-10-10T19:05:00-04:00"
  },
  "isError": false
}
```

## Tag guests

MCP tool: `paperless-post_tag_guests`

Access: write.

Adds one Guest Tag to the guests you list; the tag is created if it does not exist. Guest Tags need All Access pricing or Paperless Pro, otherwise the call fails. Tags reach no one and one call removes them, so this call needs no confirmation.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | Card or Flyer ID from list_events. |
| `guest_ids` | string[] | yes | Guest IDs from list_guests. |
| `tag` | string | yes | Tag name; created if it does not exist. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "paperless-post_tag_guests",
    "arguments": {
      "event_id": "ev_8F3K2Q",
      "guest_ids": [
        "g_20417",
        "g_20433"
      ],
      "tag": "lodging"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8F3K2Q",
    "tag": "lodging",
    "tagged": 2
  },
  "isError": false
}
```