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:

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 under the assistant. A mail with a subject becomes a task named by that subject, kept under your assistant. 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.

Your other tasks, the ones outside the assistant, are your own work and are not part of the inbox. They are read too only when you ask for them, with tasks=all.

Read the inbox

GET /inbox

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

Answered 200:

{
  "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

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:

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:

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

{ "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.

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 under it written to most recently. With tasks=all it is the room and your 100 tasks written to most recently; send tasks=all on every page you go on to.

Mail to the assistant

An assistant's own address is in the answer of the assistant endpoint. 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.

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

For machines

• This page as Markdown: https://worklyn.com/journals/inbox/install.md
• The whole API, machine-readable: https://worklyn.com/openapi.json
• An index of Worklyn for language models: https://worklyn.com/llms.txt