# API Reference
The lists.sr.ht API allows you to browse, create, and subscribe to mailing lists
on lists.sr.ht programmatically. This API follows the [standard sourcehut API
conventions](../api-conventions.md).
## Authentication
Authentication is done via the [meta.sr.ht OAuth
flow](https://man.sr.ht/meta.sr.ht/oauth-api.md). The following OAuth scopes are
available for lists.sr.ht:
- **emails:read**: read emails received from lists.sr.ht users
- **lists:read**, **list:write**: read & write your mailing lists
- **subs:read**, **subs:write**: read & write your subscriptions
## Resources
### Email resource
```json
{
"id": integer,
"created": "timestamp",
"subject": "message subject",
"message_id": "value of the Message-ID header",
"parent_id": integer or null,
"thread_id": integer,
"list": { short form list resource },
"sender": { short form user resource } or null,
"is_patch": boolean,
"is_request_pull": boolean,
"replies": integer,
"participants": integer,
"envelope": "original email"
}
```
**Notes**
- The short form omits `is_patch`, `is_request_pull`, `replies`, `participants`,
and `envelope`.
- The sender is null of the sender's email address could not be associated with
a sr.ht account.
### Mailing list resource
```json
{
"created": "timestamp",
"updated": "timestamp",
"name": "name of this list",
"owner": { short form user resource },
"description": "list description (markdown)",
"permissions": {
"nonsubscriber": "list,of,permissions",
"subscriber": "list,of,permissions",
"account": "list,of,permissions"
}
}
```
**Notes**
- The permissions which may appear in each `permissions` field are browse,
reply, and post.
- The short form omits everything except for name and owner.
### Subscription resource
```json
{
"id": integer,
"created": "timestamp",
"list": { short form list resource }
}
```
## Endpoints
**Note**: in all routes, `:username` may be substituted with an email address,
and `:email-id` may be the email's either of the "id" or "message_id" values.
### GET /api/:username
Retrieves a user resource.
### GET /api/user
Equivalent to [/api/:username](#GET-apiusername), implies the authenticated
user.
### GET /api/user/:username/emails
List of [email resources](#email-resource) received from this user.
**OAuth scope**: `emails:read`
### GET /api/user/emails
Equivalent to [/api/:username/emails](#GET-apiusernameemails), implies the
authenticated user.
**OAuth scope**: `emails:read`
### GET /api/emails/:email-id
Retrieves an [email resource](#email-resource).
**OAuth scope**: `emails:read`
### GET /api/user/:username/emails/:email-id
Equivalent to [GET /api/emails/:email-id](#GET-apiemailsemail-id); `username` is
discarded.
**OAuth scope**: `emails:read`
### GET /api/thread/:email-id
Retrieves an array of each email implicated in the thread identified by its
first message's `:email-id`.
**OAuth scope**: `emails:read`
**Response**
```json
[
{ short form email resource },
...
]
```
### GET /api/user/:username/thread/:email-id
Equivalent to [GET /api/thread/:email-id](#GET-apithreademail-id); `username` is
discarded.
**OAuth scope**: `emails:read`
### GET /api/user/:username/lists
List of [mailing list resources](#mailing-list-resource) owned by this user.
**OAuth scope**: `lists:read`
### GET /api/lists
Equivalent to [/api/:username/lists](#GET-apiusernamelists), implies the
authenticated user.
**OAuth scope**: `lists:read`
### POST /api/lists
Creates a new [mailing list resource](#mailing-list-resource).
**OAuth scope**: `lists:write`
**Request body**
```json
{
"name": "mailing list name",
"description": "mailing list description (markdown)" (optional)
}
```
**Response**
The new [mailing list resource](#mailing-list-resource).
### GET /api/user/:username/lists/:list-name
Retrieves a [mailing list resource](#mailing-list-resource).
**OAuth scope**: `lists:read`
### GET /api/lists/:list-name
Equivalent to [/api/:username/lists/:list-name](#GET-apiusernamelistslist-name),
implies the authenticated user.
**OAuth scope**: `lists:read`
### PUT /api/lists/:list-name
Updates a [mailing list resource](#mailing-list-resource).
**OAuth scope**: `lists:write`
**Request body**
```json
{
"description": "mailing list description (markdown)" (optional)
}
```
**Response**
The updated [mailing list resource](#mailing-list-resource).
### GET /api/user/:username/lists/:list-name/posts
List of [email resources](#email-resource) posted to this list.
**OAuth scope**: `lists:read`
### GET /api/lists/:list-name/posts
Equivalent to
[/api/:username/lists/:list-name/posts](#GET-apiusernamelistslist-nameposts),
implies the authenticated user.
**OAuth scope**: `lists:read`
### GET /api/subscriptions
List of [subscription resources](#subscription-resources)
**OAuth scope**: `subs:read`
### POST /api/subscriptions
Create a new [subscription resources](#subscription-resources)
**OAuth scope**: `subs:write`
**Request body**
```json
{
"list": "~owner/list-name"
}
```
**Response**
The new [subscription resource](#subscription-resource).
### GET /api/subscriptions/:sub-id
Retrieves a [subscription resource](#subscription-resource).
**OAuth scope**: `subs:read`
### DELETE /api/subscriptions/:sub-id
Deletes this [subscription resource](#subscription-resource).
**OAuth scope**: `subs:write`
## Webhooks
### /api/user/...
Webhook for user events. Includes the [standard webhook
endpoints](../api-conventions.md#webhooks)
#### email:received
Issued when lists.sr.ht receives an email from this user.
**OAuth scope**: `emails:read`
**Request body**
The new [email resource](#email-resource).
#### list:create
Issued when the user creates a new mailing list.
**OAuth scope**: `lists:read`
**Request body**
The new [mailing list resource](#mailing-list-resource).
#### subscription:create
Issued when the user subscribes to a mailing list.
**OAuth scope**: `subs:read`
**Request body**
The new [subscription resource](#subscription-resource).
#### subscription:remove
Issued when the user unsubscribes from a mailing list.
**OAuth scope**: `subs:read`
**Request body**
```json
{
"id": integer ID of the affected subscription resource
}
```
### /api/user/:username/lists/:list-name/...
Webhook for mailing list events. Includes the [standard webhook
endpoints](../api-conventions.md#webhooks)
#### post:received
Issued when a new email is posted to this list.
**OAuth scope**: `lists:read`
**Request body**
The new [email resource](#email-resource).
#### list:update
Issued when the list details are updated.
**OAuth scope**: `lists:read`
**Request body**
The updated [mailing list resource](#mailing-list-resource).
