Email and chats

The email that went with a document is often as important as the document: the client’s approval, the figures someone sent, the version that was attached. Synck can keep those messages in the same repository and the same history as your files. A repository can also hold a running conversation, a chat, next to the documents it discusses.

An email file is a file

Save an email from your mail program as an .eml file, or an Outlook .msg file, into the repository’s folder, and Synck treats it like any other file:

$ cp ~/Downloads/budget-email.eml Launch/
$ synck status
A Launch/budget-email.eml

Committing it records the file’s bytes, nothing more. That is often all you need. To keep the message as an email, with its sender, recipients and attachments readable, import it instead.

Import a message

synck repository import-email reads a message and records it as an EMAIL record, in a commit of its own. --link files it in a folder:

$ synck repository import-email ~/Downloads/budget-email.eml --link Launch -m "Save Maria's budget email"
{"commit_id":"sha256:8acc73e292f1d9394d38cb11cfb872fd9721a74557340834f03dde7acc1346b6","item_id":"01a1a3f3-86fe-7145-b80b-71a1b54741ec","schema_version":1}
$ synck status
nothing to commit, working tree clean

The record keeps the sender, recipients and dates, the body, every attachment, and the exact bytes of the original .eml or .msg file. It is a record, not a file: it has no name and no place on disk, and its title is the message’s subject unless you choose another with --title. The link files it in Launch, but it does not appear in that folder on disk. The file you imported is left alone, wherever it is. Keep it outside the repository’s folder, unless you also want it committed as a file.

A recorded email never changes. Importing the same file again records a second email.

Messages that cannot be read, or that exceed the import limits (64 MiB per message and its decoded attachments, 1,000 attachments), are refused with an error, and nothing is recorded. Reading a message never fetches anything from the network.

Read it back

Email records do not appear as files in your folder, so you read them with synck item, which answers in JSON. item list --records lists records, and with --parent only those filed in that folder. This example uses jq to print one line per record:

$ synck item list --records --parent Launch | jq -r '.items[] | "\(.item_type)\t\(.item_id)"'
EMAIL	01a1a3f3-86fe-7145-b80b-71a1b54741ec
$ synck item show 01a1a3f3-86fe-7145-b80b-71a1b54741ec | jq -r .item.projection.name
Launch budget
$ synck item show 01a1a3f3-86fe-7145-b80b-71a1b54741ec | jq '.item.projection.metadata_json.mailcal | {subject, from, to, sent_at}'
{
  "subject": "Launch budget",
  "from": {
    "email": "[email protected]",
    "name": "Maria"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Sam"
    }
  ],
  "sent_at": "2026-10-23T08:00:00+00:00"
}

The full output of item show also has every other header, the hashes that identify the stored original message, and one EMAIL::ATTACHMENT subitem per attachment, with its file name. Reading items and history describes the output in detail.

To get the original message back, exactly as it was saved, export it to a new file:

$ synck item export 01a1a3f3-86fe-7145-b80b-71a1b54741ec ../original.eml
{"bytes":289,"destination":"../original.eml","item_id":"01a1a3f3-86fe-7145-b80b-71a1b54741ec","schema_version":1}

In the history

synck log and synck show list file and folder changes, so the import appears as 0 changes:

$ synck log -n 1
3 | 2026-11-04 01:26 +01:00 | Alex | 0 changes | Save Maria's budget email

synck repository log . lists every event in each commit, including the EMAIL::CREATE that recorded the message.

A recorded email is permanent, like everything else in the history. synck revert only reverses commits that change files and folders, so it refuses a commit that recorded an email. Check that a message belongs in the repository before you import it.

Keep a chat

A chat is a record too: it has a title but no place in a folder, so it never appears on disk. Create one with synck repository create-chat, then add messages from UTF-8 text files:

$ synck repository create-chat "Launch review"
{"commit_id":"sha256:28e089ba17c136bc01a6bf09493a49922622e68c23e177252f3dca99633c8271","item_id":"01a1a3f3-87ce-7444-9328-23ebdf82b62c","schema_version":1}
$ printf 'Sent to the client.' > ../message.txt
$ synck repository append-chat 01a1a3f3-87ce-7444-9328-23ebdf82b62c ../message.txt --attachment Launch/proposal.txt
{"commit_id":"sha256:7468a3b523c81d70d14074cdebdee20ddc773909e56135da25b59b6857dc06f0","schema_version":1}

Each command records one commit, and each message records your author name as its sender. --attachment stores a copy of a file with the message; repeat it for several files. Read the conversation back with synck item show, as described in Reading items and history. Like an imported email, the message file is read and left alone, so keep it outside the repository’s folder, or add it to .synckignore, if you do not want it committed as a file later.