Update email-mcp
After this page, you can install a newer version of email-mcp. Your accounts, your settings and the activity log stay. You do not connect your accounts again.
What an update changes
- An update replaces only the program file. The data folder (the folder where email-mcp keeps its data, see Where the data lives), the master key (the key that protects your stored passwords, see The master key) and the config of your AI (artificial intelligence) app stay as they are.
- A new version can need a new layout of the database. The first command of
the new version that opens the data folder, such as
serve,setupordoctor, changes the layout by itself. Each of these steps is a migration (a change of the database to the layout that a version needs). Each migration runs in one transaction (a group of changes that is saved completely or not at all). When a migration fails, the database stays as it was before that migration. - After a newer version has opened the data folder, an older version refuses it. So to go back to an older version, you need a copy of the data folder that you made before the update. See Go back to an older version.
- email-mcp does not look for new versions by itself. You check for them.
Find out if there is a new version
-
Run this command in a terminal (a window where you type commands). It prints the name and the version of the program:
email-mcp versionYou should see
email-mcpand the version, for exampleemail-mcp 0.6.2. A program that you built yourself printsemail-mcp dev:- For a program from
go install, see Go. - For a program that you built from the source code, run
git describe --tagsin the folder of the code. Git is the tool that keeps the versions of the code. The command prints the tag (the git name of a release), such asv0.6.2. A name such asv0.6.2-18-ga90aabcmeans 18 commits (saved changes) afterv0.6.2, at the commita90aabc.
- For a program from
-
Compare it with the newest version on the GitHub releases. GitHub can tell you about each new release: on the page of the repository (the project on GitHub), choose Watch, then Custom, tick Releases, and choose Apply.
-
Read the release notes (the list of changes of a release) of each version after yours. The file
CHANGELOG.mdholds the same notes. While the version is below 1.0.0, a new middle number (such as 0.6.0 after 0.5.2) can hold a breaking change (a change that can need a step from you). The notes list it under “⚠ BREAKING CHANGES”. A new last number (such as 0.6.2 after 0.6.1) has no breaking change.
Before you update
-
Stop every program that uses the data folder:
serve,setup, and the AI apps that start email-mcp. A program that still runs keeps the old version in memory, and the old version does not know the new layout of the database. On Windows, a running program file cannot be replaced.A stop can take some time, because email-mcp first sends the messages that are due. The messages that are left stay queued, and the next program that sends mail sends them. See When email-mcp stops.
-
Check that no email-mcp program runs. On macOS and Linux, this command lists the running programs whose name contains
email-mcp.-lprints the name of each program after its process ID (identifier: the number of a running program):pgrep -l email-mcpIt prints nothing when no email-mcp runs. A line such as
29057 email-mcpis a program that still runs: find the app or the terminal that started it, and stop it. In the Command Prompt (the terminal of Windows), this command lists the running programs with the nameemail-mcp.exe./FIfilters the list:tasklist /FI "IMAGENAME eq email-mcp.exe"It prints “INFO: No tasks are running which match the specified criteria.” when no email-mcp runs.
-
Look at the outbox (the queue of messages that wait to go out). This command lists the messages in it:
email-mcp outbox listYou should see “No message waits to go out.” When it lists a message, that message is also in the copy of the next step. If you ever put the copy back, the message waits again, and it can go out a second time. Write down its ID. Go back to an older version says what to do with it.
-
Copy the data folder. This step is optional, but without the copy you cannot go back to the older version. The commands below copy the folder to
email-mcp-backup-0.6.2in your home folder. Write your own version, fromemail-mcp version, instead of0.6.2.-Rcopies the folder and everything in it.-pkeeps the modes (who may read and write a file) and the times of the files.The second path must not exist yet. When it exists,
cpputs the copy inside it, as a folderemail-mcp, and prints no error. So use a new name for each copy, for example with the version in it.The first part of each command is the data folder of your system. See Where the data lives. On macOS, run:
cp -Rp "$HOME/Library/Application Support/email-mcp" "$HOME/email-mcp-backup-0.6.2"On Linux, run this command.
${XDG_DATA_HOME:-$HOME/.local/share}is the folder inXDG_DATA_HOME, or~/.local/sharewhenXDG_DATA_HOMEis not set:cp -Rp "${XDG_DATA_HOME:-$HOME/.local/share}/email-mcp" "$HOME/email-mcp-backup-0.6.2"The commands print nothing when they work. To check the copy, run
ls "$HOME/email-mcp-backup-0.6.2"(lslists the files of a folder). You should seeemail-mcp.dband the other files of the data folder. If you also see a folderemail-mcp, the name existed already, and the new copy is in that folder: make the copy again with a new name.On Windows, type
%AppData%in the address bar of the file explorer, and copy the folderemail-mcpto another place, with a new name. If you use--data-dirorEMAIL_MCP_DATA_DIR, copy that folder instead.The copy holds your encrypted passwords, so keep it private, as the data folder. The master key is not in the copy. The copy opens only with the master key that you used when you made it, so keep that key while you keep the copy.
Install the new version
Use the same way that you used to install email-mcp. Each way below puts the new version where the old one was. So the config of your AI app needs no change.
Homebrew
The first command updates the list of packages of Homebrew (a package manager:
a program that installs other programs), also the list of the tap (a repository
of Homebrew packages) EmadMokhtar/homebrew-tap. Without it, Homebrew may not
know the new version yet. The second command installs the new version of the
cask (a package of a ready-made program). --cask says that the package is a
ready-made program:
brew update
brew upgrade --cask emadmokhtar/tap/email-mcp
When it ends without an error, go to After the update. When the newest version is already installed, Homebrew says “Not upgrading email-mcp, the latest version is already installed”.
The program is not signed by Apple. So the cask removes the “quarantine” mark of the new version, as it did at the install. The quarantine mark is the flag that macOS puts on a downloaded file, and that makes Gatekeeper (the macOS program check) look at it. See Install email-mcp.
The path of the program, such as /opt/homebrew/bin/email-mcp, stays the
same. It is a link to the program in a folder of Homebrew. Do not put the path
of that folder, such as /opt/homebrew/Caskroom/email-mcp/0.6.2/email-mcp, in
the config of your AI app: it holds the version number, so it changes with
each version.
A release archive
Do the steps of A release archive again, with the archive (the file that holds the program) of the new version: download it, check it, unpack it, and clear the quarantine mark on macOS (see the Homebrew section above). Then put the program in the same folder as before.
If you do not remember the folder, which email-mcp prints the path of the
program on macOS and Linux, and where email-mcp prints it on Windows.
On macOS and Linux, the install page puts the program in /usr/local/bin. If
you put it in another folder, use that folder in the commands below. That
folder belongs to the administrator, so each command starts with sudo (it
runs the command as the administrator). The first command removes the old
program, so that the copy is a new file and not a change of the file that ran
before. The second command copies the new program from the folder where you
unpacked it:
sudo rm /usr/local/bin/email-mcp
sudo cp email-mcp /usr/local/bin/
They print nothing when they work. On Windows, copy email-mcp.exe into the
folder of the old one, such as C:\Tools, and choose to replace the file.
Then go to After the update.
Go
Run the same command as at the install. Go is a programming language, and
go install downloads the code, builds the program, and replaces the old
program. @latest means the newest release. To choose a version, write it
instead, such as @v0.6.2. Go versions and git tags start with v:
go install github.com/EmadMokhtar/email-mcp-go/cmd/email-mcp@latest
A program that go install built prints email-mcp dev for email-mcp version. To see its version, run this command on macOS and Linux. -m prints
the modules (the packages of Go code) that are built into the program:
go version -m "$(which email-mcp)"
The line that starts with mod holds the version, for example
mod github.com/EmadMokhtar/email-mcp-go v0.6.2. Then go to
After the update.
From the source code
Run these commands in the folder of the code. make is a tool that runs the build steps of a project. Choose one of the two ways below.
To build the newest release, the first command gets the tags of the new
releases. The second command switches the code to one tag. Write the version
that you want instead of v0.6.2. --detach is needed because a tag is not a
branch (a line of work in git). Git calls this state a detached HEAD: the code
is at the tag, and on no branch. The third command builds the program:
git fetch --tags
git switch --detach v0.6.2
make build # writes bin/email-mcp
To build the newest code instead, the first command goes back to the branch
main (the main line of the code). This is needed after a build of a tag,
because git pull does not work on no branch. The second command brings the
newest commits of main. That code can hold changes that are not in a release
yet:
git switch main
git pull
make build # writes bin/email-mcp
Copy bin/email-mcp to the same folder as before, with the commands of A
release archive. Then go to
After the update.
The container image
The container image is not for daily use on your own computer (see Containers). Docker is a tool that runs programs in containers (a way to run a program in its own closed space). To test a new version, pull the image with the tag (the name of one version of an image) of that version, and use the new tag where you used the old one.
The image tag is the version without the v, such as 0.6.2. This differs
from Go versions and git tags, such as v0.6.2. The tag latest names
the newest version that is not a pre-release (a test version, such as
0.7.0-rc.1). This command downloads the image of one version:
docker pull ghcr.io/emadmokhtar/email-mcp:0.6.2
To check the new image, see Verifying a release.
After the update
-
Run
email-mcp version. You should see the new version. -
If your master key is a file, set the environment variable
EMAIL_MCP_KEK(a named setting that a program reads from its surroundings) in this terminal first, with the same value as in the config of your AI app. Then run this command. It checks the install, and it opens the data folder, so it also runs the migrations of the new version:email-mcp doctorNo line should have
FAIL. The other lines haveok, sometimes with a note, such asaccounts: ok (none is connected). If a line hasFAIL, see Troubleshooting. A failed account can also come from the mail server, and not from the update. -
Start your AI apps again, and
serveandsetupif you use them. Each AI app now starts the new version. -
If the release notes list a breaking change, do the steps that they name.
Go back to an older version
After a newer version has opened the data folder, an older version refuses it. Each command of the older version that opens the data folder then stops with the error “this data was written by a newer email-mcp; install that version or newer”. The older version does not know the newer layout of the database, so it changes nothing. To go back, you need the copy of the data folder from Before you update.
The copy holds the data of the moment when you made it, and nothing after it. This matters for two kinds of data:
- Newer data is missing. For example, the activity log after that moment
is missing, and so are the messages that the newer version queued. So with
the newer version, first run
email-mcp outbox list. If a message waits, let it go out, or cancel it withemail-mcp outbox cancel <id>. See Activity and undo. - Older data comes back. A message that waited in the outbox when you made the copy waits again, also when the newer version has sent it since. The same is true for a send or a move to the Trash that waited for your answer. Step 4 below handles them.
Then do these steps:
-
Stop every program that uses the data folder, as in Before you update.
-
Install the older version. Use a release archive of that version, or
go installwith that version, such as@v0.6.1. Homebrew installs only the version that the tap names, which is the newest one. So remove the cask first withbrew uninstall --cask emadmokhtar/tap/email-mcp, and install the older version from a release archive. The path of the program then changes, so also change it in the config of your AI app. -
Put the copy back. On macOS, the first command moves the current data folder away to
email-mcp-data-0.7.0in your home folder, so you keep it. Write the newer version instead of0.7.0. This path must not exist yet: when it exists,mvputs the folder inside it. The second command copies the copy to the place of the data folder, and keeps the modes:mv "$HOME/Library/Application Support/email-mcp" "$HOME/email-mcp-data-0.7.0" cp -Rp "$HOME/email-mcp-backup-0.6.2" "$HOME/Library/Application Support/email-mcp"On Linux, use
${XDG_DATA_HOME:-$HOME/.local/share}/email-mcpas the path of the data folder. On Windows, rename the folderemail-mcpin%AppData%, and copy your copy into%AppData%with the nameemail-mcp. -
Before you start any AI app,
serveorsetup, runemail-mcp outbox listwith the older version. Each message that it lists waited when you made the copy. The newer version may have sent it already: look in the Sent folder of the account. Cancel each message that went out already withemail-mcp outbox cancel <id>. It prints “Cancelled the send” and the ID, and “It will not go out.” A send or a move to the Trash that you answered with the newer version can wait for your answer again. When you open the web pages again, do not approve it a second time: reject it on Waiting for you. -
Run
email-mcp doctor, withEMAIL_MCP_KEKset as in After the update. No line should haveFAIL.
Without a copy, there are two ways. Install the newer version again, or start with an empty data folder: move the data folder away, and connect your accounts again (see Connect your first account). An empty data folder has none of your accounts, settings or activity log.