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.