6.7 KiB
title |
---|
lists.sr.ht API reference |
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.
Authentication
Authentication is done via the meta.sr.ht OAuth flow. 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
{
"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
, andenvelope
. - The sender is null if the sender's email address could not be associated with a sr.ht account.
Mailing list resource
{
"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
{
"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, implies the authenticated user.
GET /api/user/:username/emails
List of email resources received from this user.
OAuth scope: emails:read
GET /api/user/emails
Equivalent to /api/:username/emails, implies the authenticated user.
OAuth scope: emails:read
GET /api/emails/:email-id
Retrieves an email resource.
OAuth scope: emails:read
GET /api/user/:username/emails/:email-id
Equivalent to GET /api/emails/:email-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
[
{ short form email resource },
...
]
GET /api/user/:username/thread/:email-id
Equivalent to GET /api/thread/:email-id; username
is
discarded.
OAuth scope: emails:read
GET /api/user/:username/lists
List of mailing list resources owned by this user.
OAuth scope: lists:read
GET /api/lists
Equivalent to /api/:username/lists, implies the authenticated user.
OAuth scope: lists:read
POST /api/lists
Creates a new mailing list resource.
OAuth scope: lists:write
Request body
{
"name": "mailing list name",
"description": "mailing list description (markdown)" (optional)
}
Response
The new mailing list resource.
GET /api/user/:username/lists/:list-name
Retrieves a mailing list resource.
OAuth scope: lists:read
GET /api/lists/:list-name
Equivalent to /api/:username/lists/:list-name, implies the authenticated user.
OAuth scope: lists:read
PUT /api/lists/:list-name
Updates a mailing list resource.
OAuth scope: lists:write
Request body
{
"description": "mailing list description (markdown)" (optional)
}
Response
The updated mailing list resource.
GET /api/user/:username/lists/:list-name/posts
List of email resources posted to this list.
OAuth scope: lists:read
GET /api/lists/:list-name/posts
Equivalent to /api/:username/lists/:list-name/posts, implies the authenticated user.
OAuth scope: lists:read
GET /api/subscriptions
List of subscription resources
OAuth scope: subs:read
POST /api/subscriptions
Create a new subscription resources
OAuth scope: subs:write
Request body
{
"list": "~owner/list-name"
}
Response
The new subscription resource.
GET /api/subscriptions/:sub-id
Retrieves a subscription resource.
OAuth scope: subs:read
DELETE /api/subscriptions/:sub-id
Deletes this subscription resource.
OAuth scope: subs:write
Webhooks
/api/user/...
Webhook for user events. Includes the standard webhook endpoints
email:received
Issued when lists.sr.ht receives an email from this user.
OAuth scope: emails:read
Request body
The new email resource.
list:create
Issued when the user creates a new mailing list.
OAuth scope: lists:read
Request body
The new 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:remove
Issued when the user unsubscribes from a mailing list.
OAuth scope: subs:read
Request body
{
"id": integer ID of the affected subscription resource
}
/api/user/:username/lists/:list-name/...
Webhook for mailing list events. Includes the standard webhook endpoints
post:received
Issued when a new email is posted to this list.
OAuth scope: lists:read
Request body
The new email resource.
list:update
Issued when the list details are updated.
OAuth scope: lists:read
Request body
The updated mailing list resource.