~sircmpwn/sr.ht-docs

ref: 034d92ce14251297c41f68cfbf7e37df5fe80d0f sr.ht-docs/lists.sr.ht/api.md -rw-r--r-- 6.7 KiB
034d92ceDrew DeVault Add YAMl frontmatter to all pages 2 years ago

#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, and envelope.
  • 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.