> Worklyn documentation. Index for language models: https://worklyn.com/llms.txt

# Inbox

The inbox is everything said with an account's assistant, newest first: what the account wrote, what the assistant answered, and what arrived from outside, such as mail sent to the assistant's own address.

- `GET /inbox` answers a page of messages. It never makes or changes anything.

The base address is `https://worklyn.com`. Answers are JSON.

## Authentication

The call reads the inbox of the account the credentials name. There is no account id in the address, so one account can never read another's inbox.

Send one of these with the request:

| Credential | How to send it |
|---|---|
| Session token | `Authorization: Bearer <token>`, or the `id` cookie set when the person signs in at worklyn.me |
| OAuth access token | `Authorization: Bearer <token>` |
| App token | `Authorization: Bearer <token>` together with `X-App-Id: <app id>` |

A request with no credentials, or with ones that are not valid, is answered `401` with the code `unauthorised`.

## Where messages live

A message is in one of two places, and the inbox reads both together.

- **The room with the assistant.** What the account and its assistant say to each other, and a mail that has no subject.
- **A task the assistant is in.** A mail with a subject becomes a task named by that subject. A reply in the same mail conversation joins that task, and the task keeps its first name: `Re:` and `Fwd:` are dropped.

Each message says which it is in through its `task` field.

## Read the inbox

`GET /inbox`

| Parameter | Type | Meaning |
|---|---|---|
| `limit` | integer, optional | How many messages to answer, from 1 to 200. Left out: 50. |
| `before` | date-time, optional | Only messages older than this time. Send the `before` of the page already read. |

```bash
curl "https://worklyn.com/inbox?limit=20" \
  -H "Authorization: Bearer $WORKLYN_TOKEN"
```

Answered `200`:

```json
{
  "messages": [
    {
      "id": "c1f0a9d2-6b1e-8a43-9d77-2f5b8e0a4c11",
      "created": "2026-10-12T15:30:29.001Z",
      "from": "other",
      "name": "Sam Dube",
      "email": "sam@example.com",
      "subject": "Quote",
      "task": { "id": "8e2b7c54-91aa-8f10-b3c6-0d4e7a215f90", "name": "Quote" },
      "text": "[file]",
      "htmlUrl": null,
      "file": {
        "id": "5a7d3e18-0c42-8b9f-a6e1-7f20c9d4b385",
        "name": "quote.pdf",
        "type": "application/pdf",
        "kind": "document",
        "url": "/files/5a7d3e18-0c42-8b9f-a6e1-7f20c9d4b385"
      }
    },
    {
      "id": "0d9e4b71-3f58-8c26-8a14-6b7c2e9f5d03",
      "created": "2026-10-12T15:30:29.000Z",
      "from": "other",
      "name": "Sam Dube",
      "email": "sam@example.com",
      "subject": "Quote",
      "task": { "id": "8e2b7c54-91aa-8f10-b3c6-0d4e7a215f90", "name": "Quote" },
      "text": "Please see the quote attached.",
      "htmlUrl": "/files/b6c1e0f4-7a29-8d53-9e08-4c5d1a7f2b66",
      "file": null
    }
  ],
  "before": "2026-10-12T15:30:29.000Z",
  "more": true
}
```

An account with no assistant yet is answered an empty list: `{ "messages": [], "more": false }`.

## A message

| Field | Type | Meaning |
|---|---|---|
| `id` | string | The message's id. |
| `created` | date-time | When it was written or, for a mail, sent. |
| `from` | string | Who wrote it: `assistant`, `you` (the account itself) or `other` (someone else, such as a mail's sender). |
| `name` | string or null | The writer's name, when it is known. |
| `email` | string or null | The sender's address, for a message that came by mail. |
| `subject` | string or null | The mail's subject. |
| `task` | object or null | The task the message is in, as `id` and `name`. `null` in the room with the assistant. |
| `text` | string | The message's words. For a mail drawn in HTML, the words read out of it. |
| `htmlUrl` | string or null | For a mail drawn in HTML: where the mail as its sender drew it is read from. |
| `file` | object or null | The file the message shows, when it shows one. |

A mail with more than 16,000 characters of words is cut, and says so at its end.

### Files and attachments

Each file a mail has attached is a message of its own, a millisecond after the mail's words, so the order is the mail's own. Its `file` holds:

| Field | Type | Meaning |
|---|---|---|
| `id` | string | The file's id. |
| `name` | string | Its name. |
| `type` | string or null | Its media type, such as `application/pdf`. |
| `kind` | string | `image`, `video`, `document` or `voice`. |
| `url` | string | Where a link to the file's bytes is read from. |

`file.url` and `htmlUrl` are addresses on `https://worklyn.com`. A `GET` on one, with the same credentials, answers a short-lived link to the contents:

```bash
curl https://worklyn.com/files/5a7d3e18-0c42-8b9f-a6e1-7f20c9d4b385 \
  -H "Authorization: Bearer $WORKLYN_TOKEN"
```

```json
{ "url": "https://bucket.worklyn.com/files/…" }
```

That link needs no credentials and lasts five minutes. Ask again for a new one.

The page behind `htmlUrl` is kept so that it runs no script and loads nothing from the network. Pictures the mail links to do not show; pictures it carries inside itself do.

## Read older messages

The inbox is read a page at a time, newest first. While `more` is `true`, older messages remain: send the `before` of the page you have as the `before` of the next call.

```bash
curl "https://worklyn.com/inbox?limit=20&before=2026-10-12T15:30:29.000Z" \
  -H "Authorization: Bearer $WORKLYN_TOKEN"
```

When `more` is `false` there is no `before`, and nothing older to read.

Each page reads the room with the assistant and the 100 tasks written to most recently.

## Mail to the assistant

An assistant's own address is in the answer of [the assistant endpoint](https://worklyn.com/docs/assistant). Mail sent there is read once a minute and shows in the inbox as `from: "other"`, with the sender's `name` and `email`.

- Up to 10 files a mail are kept, each up to 5 MB. Larger ones are left out.
- Mail whose sender cannot be confirmed (no DKIM or SPF pass) is not kept.
- The assistant does not answer mail. It is saved for the account to read.

## Errors

An error is answered as JSON with a code and a sentence for a person.

```json
{
  "ok": false,
  "code": "invalid",
  "error": "limit: Invalid value: Expected <=200 but received 500"
}
```

| Status | Code | When |
|---|---|---|
| `400` | `invalid` | `limit` is not a number from 1 to 200, `before` is not a date-time, or another parameter is sent. |
| `401` | `unauthorised` | The credentials are missing or not valid. |

## For machines

- This page as Markdown: [https://worklyn.com/docs/inbox.md](https://worklyn.com/docs/inbox.md)
- The whole API, machine-readable: [https://worklyn.com/openapi.json](https://worklyn.com/openapi.json)
- An index of Worklyn for language models: [https://worklyn.com/llms.txt](https://worklyn.com/llms.txt)