These notes describes how to extract email from a GMail account (standard GMail or Google Workspace) and restore them with the emails organised into folders as they were within GMail.

There are times you might want to migrate away from Google's GMail service.

For example, at the time of writing a major reason is if you have a private Google Workspace instance which was free when you originally set it up. Google are going to start charging for those instances on a per-account so unless you can afford it you can archive your email and optionally upload them to a new service.

Exporting from GMail

Exporting your account data is simple. Head over to https://takeout.google.com/ whilst logged in to Google.

If you are logged into multiple accounts you might need to switch to the one you want to export once on that page via your avatar at the top right of the page.

On that page you will see most of the options pre-selected. The first one is normally unselected due to its size. You can either accept the defaults or, if you just want one like email or a custom set, select Deselect all then select the ones you want. For this exercise you want Mail selected.

Select Next and you are presented with the delivery method. Here keep the default Export once and select Create export.

Now wait. This can take some time, even a day or two, depending on how big your export is going to be.

Once it's done you will receive an email on that account telling you it's ready and a link to download it. You'll get a few days to download the extract.

Handling the export

Once you have received the notification, download the generated Zip archive. If the archive is larger than 2Gb it will be split into multiple files, so you have to download all of them. I suggest doing this in am empty directory.

Next extract the files from the archive. You should get a new Takeout directory.

Depending on what you extracted, Mail should be inside Takeout/Mail as a .mbox file. Copy these to a new empty directory which you will use as the source for the next step.

Recreating email folders

With Gmail there's actually no concept of a folder containing your emails. It's all done with labels. So, if you import this into an email client you will just get a single monolithic folder with every email within it. Not what you were expecting.

All is not lost however as Gmail stores an emails labels as a non-standard X-Gmail-Labels header.

To fix this there's a handy python script called gmail-mboxsplitter.

Create a new empty folder and inside that clone its repository:

1git clone https://github.com/f00b4r0/gmail-mboxsplitter.git

Next create a subdirectory next to this called src and copy the .mbox file extracted into it. If there's multiple files then copy them all. For my first run it was called All mail Including Spam and Trash.mbox. In the end this directory should only contain mbox files and nothing else.

Now create another subdirectory. This will be where we will create the new mbox files, one per folder. Move into this new blank directory and run for each .mbox file under src:

1../gmail-mboxsplitter/mbox_split.py --infile ../src/All\ mail\ Including\ Spam\ and\ Trash.mbox

Now wait. The script will process each email in that .mbox file and write it to each new mbox, one for each label.

Depending on how large your old mailbox is it can take some time.

It will also log a lot, so don't do this remotely.

Once it has completed, you can then import these into your favourite email client. You don't need to do all of them, just the ones you want or use regularly & the others become an archive.