Worklyn Docs

Inbox

Copy as MarkdownView MarkdownOpen in ClaudeOpen in ChatGPT

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:

CredentialHow to send it
Session tokenAuthorization: Bearer <token>, or the id cookie set when the person signs in at worklyn.me
OAuth access tokenAuthorization: Bearer <token>
App tokenAuthorization: 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

ParameterTypeMeaning
limitinteger, optionalHow many messages to answer, from 1 to 200. Left out: 50.
beforedate-time, optionalOnly messages older than this time. Send the before of the page already read.
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

FieldTypeMeaning
idstringThe message's id.
createddate-timeWhen it was written or, for a mail, sent.
fromstringWho wrote it: assistant, you (the account itself) or other (someone else, such as a mail's sender).
namestring or nullThe writer's name, when it is known.
emailstring or nullThe sender's address, for a message that came by mail.
subjectstring or nullThe mail's subject.
taskobject or nullThe task the message is in, as id and name. null in the room with the assistant.
textstringThe message's words. For a mail drawn in HTML, the words read out of it.
htmlUrlstring or nullFor a mail drawn in HTML: where the mail as its sender drew it is read from.
fileobject or nullThe 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:

FieldTypeMeaning
idstringThe file's id.
namestringIts name.
typestring or nullIts media type, such as application/pdf.
kindstringimage, video, document or voice.
urlstringWhere 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:

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 written to most recently.

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"
}
StatusCodeWhen
400invalidlimit is not a number from 1 to 200, before is not a date-time, or another parameter is sent.
401unauthorisedThe credentials are missing or not valid.

For machines