# Paperless Post API

> Every Paperless Post endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/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 endpoints for Paperless Post. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/paperless-post`
- 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 |
|---|---|---|
| `list_events` | read | Your Cards and Flyers from My Events, with type, date and send status. |
| `get_event` | read | Event details: title, host, date, time, location and the design type. |
| `list_guests` | read | The Tracking page: each guest or group with status, number attending and Guest Tags. |
| `get_guest` | read | One guest: status, number attending and the messages sent to them. |
| `export_guest_list` | read | The Tracking page as a CSV download link, with each guest's RSVP status. |
| `list_contacts` | read | Your Address Book: names, emails and phone numbers saved for reuse. |
| `add_guests` | write | Add guests to the unsent guest list of an event. Nothing is sent until send_invitation. |
| `send_invitation` | write | Send the Card or Flyer to everyone on the unsent list, now or at a set time. |
| `send_message` | write | Broadcast from Messages & Reminders to guests by status and Guest Tag. |
| `send_private_message` | write | Message one guest in their message log. |
| `tag_guests` | write | Add a Guest Tag to guests. Tags are visible to hosts and co-hosts only. |

## List events

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/list_events \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("paperless-post", "list_events")
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'list_events');
```

**CLI**

```bash
cotlet call paperless-post list_events
```

### Example response

```json
{
  "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
}
```

## Get event

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/get_event \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'
```

**Python**

```python
result = client.call("paperless-post", "get_event", {"event_id":"event_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'get_event', {"event_id":"event_8c41d2"});
```

**CLI**

```bash
cotlet call paperless-post get_event --data '{"event_id":"event_8c41d2"}'
```

### Example response

```json
{
  "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"
}
```

## List guests

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/list_guests \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'
```

**Python**

```python
result = client.call("paperless-post", "list_guests", {"event_id":"event_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'list_guests', {"event_id":"event_8c41d2"});
```

**CLI**

```bash
cotlet call paperless-post list_guests --data '{"event_id":"event_8c41d2"}'
```

### Example response

```json
{
  "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
}
```

## Get guest

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/get_guest \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2","guest_id":"guest_8c41d2"}'
```

**Python**

```python
result = client.call("paperless-post", "get_guest", {"event_id":"event_8c41d2","guest_id":"guest_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'get_guest', {"event_id":"event_8c41d2","guest_id":"guest_8c41d2"});
```

**CLI**

```bash
cotlet call paperless-post get_guest --data '{"event_id":"event_8c41d2","guest_id":"guest_8c41d2"}'
```

### Example response

```json
{
  "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"
    }
  ]
}
```

## Export guest list

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/export_guest_list \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'
```

**Python**

```python
result = client.call("paperless-post", "export_guest_list", {"event_id":"event_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'export_guest_list', {"event_id":"event_8c41d2"});
```

**CLI**

```bash
cotlet call paperless-post export_guest_list --data '{"event_id":"event_8c41d2"}'
```

### Example response

```json
{
  "event_id": "ev_8F3K2Q",
  "rows": 41,
  "download_url": "https://files.cotlet.example/exports/ev_8F3K2Q-guests.csv"
}
```

## List contacts

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/list_contacts \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("paperless-post", "list_contacts")
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'list_contacts');
```

**CLI**

```bash
cotlet call paperless-post list_contacts
```

### Example response

```json
{
  "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
}
```

## Add guests

`POST https://cotlet.dev/api/v1/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 }. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/add_guests \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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"}]}'
```

**Python**

```python
result = client.call("paperless-post", "add_guests", {"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"}]})
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'add_guests', {"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"}]});
```

**CLI**

```bash
cotlet call paperless-post add_guests --data '{"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
{
  "event_id": "ev_8F3K2Q",
  "added": 2,
  "unsent_list_total": 2,
  "status": "unsent"
}
```

## Send invitation

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/send_invitation \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2"}'
```

**Python**

```python
result = client.call("paperless-post", "send_invitation", {"event_id":"event_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'send_invitation', {"event_id":"event_8c41d2"});
```

**CLI**

```bash
cotlet call paperless-post send_invitation --data '{"event_id":"event_8c41d2"}'
```

### Example response

```json
{
  "event_id": "ev_8F3K2Q",
  "status": "scheduled",
  "recipients": 41,
  "send_at": "2026-10-16T09:00:00-04:00"
}
```

## Send message

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/send_message \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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"]}'
```

**Python**

```python
result = client.call("paperless-post", "send_message", {"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"]})
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'send_message', {"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"]});
```

**CLI**

```bash
cotlet call paperless-post send_message --data '{"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
{
  "event_id": "ev_8F3K2Q",
  "broadcast_id": "bc_51290",
  "status": "sent",
  "recipients": 23,
  "sent_at": "2026-10-10T18:42:00-04:00"
}
```

## Send private message

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/send_private_message \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"event_8c41d2","guest_id":"guest_8c41d2","message":"message"}'
```

**Python**

```python
result = client.call("paperless-post", "send_private_message", {"event_id":"event_8c41d2","guest_id":"guest_8c41d2","message":"message"})
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'send_private_message', {"event_id":"event_8c41d2","guest_id":"guest_8c41d2","message":"message"});
```

**CLI**

```bash
cotlet call paperless-post send_private_message --data '{"event_id":"event_8c41d2","guest_id":"guest_8c41d2","message":"message"}'
```

### Example response

```json
{
  "event_id": "ev_8F3K2Q",
  "guest_id": "g_20433",
  "status": "sent",
  "sent_at": "2026-10-10T19:05:00-04:00"
}
```

## Tag guests

`POST https://cotlet.dev/api/v1/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. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/paperless-post/tag_guests \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"ev_8F3K2Q","guest_ids":["g_20417","g_20433"],"tag":"lodging"}'
```

**Python**

```python
result = client.call("paperless-post", "tag_guests", {"event_id":"ev_8F3K2Q","guest_ids":["g_20417","g_20433"],"tag":"lodging"})
```

**Node.js**

```js
const result = await cotlet.call('paperless-post', 'tag_guests', {"event_id":"ev_8F3K2Q","guest_ids":["g_20417","g_20433"],"tag":"lodging"});
```

**CLI**

```bash
cotlet call paperless-post tag_guests --data '{"event_id":"ev_8F3K2Q","guest_ids":["g_20417","g_20433"],"tag":"lodging"}'
```

### Example response

```json
{
  "event_id": "ev_8F3K2Q",
  "tag": "lodging",
  "tagged": 2
}
```