gmail-exporter

README

= gmail-exporter
Davide Cavestro <https://github.com/davidecavestro[@davidecavestro]>
// Settings:
:idprefix:
:idseparator: -
ifndef::env-github[:icons: font]
ifdef::env-github,env-browser[]
:toc: macro
:toclevels: 1
endif::[]
ifdef::env-github[]
:branch: main
:status:
:outfilesuffix: .adoc
:!toc-title:
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
// URIs:
:uri-repo: https://github.com/davidecavestro/gmail-exporter
:uri-issues: {uri-repo}/issues
:uri-search-issues: {uri-repo}/search?type=Issues
// :url-rel-file-base: {url-repo}/blob/HEAD/
:url-rel-file-base: link:
:url-license: {url-rel-file-base}LICENSE
// images:
image:https://img.shields.io/github/license/badges/shields.svg[MIT License, link=#copyright-and-license]
image:https://img.shields.io/github/languages/code-size/badges/shields.svg[GitHub code size in bytes]
image:https://img.shields.io/github/release/davidecavestro/gmail-exporter.svg[GitHub release]
image:https://img.shields.io/github/commits-since/davidecavestro/gmail-exporter/latest.svg[Github commits (since latest release)]


:imagesdir: docs/images
:icons: font

{uri-repo}[Gmail-exporter] is a command line utility for exporting a local copy of email messages and related attachments from your Gmail account.

image::export_session.svg[Example for exporting messages tagged as FOOBAR, then checking exported contents]

toc::[]

== Project status

This project is in beta test, going to apply for google oauth approval. 

== Features

- Export email messages to a spreadsheet
- Optionally export related attachments and put refs into the spreadsheet
- Optionally export messages as EML and put refs into the spreadsheet
- Exported messages filtered by label
- Optional progress status for long tasks


== Privacy policy

_Gmail-exporter_'s use of information received from Google APIs will adhere to https://developers.google.com/terms/api-services-user-data-policy#additional_requirements_for_specific_api_scopes[Google API Services User Data Policy], including the Limited Use requirements.


== Usage

Invoke the `gmail-exporter` executable passing appropriate options.


=== Quickstarts

This paragraph shows some usage examples. +
Use `./gmail-exporter help` to get the full list of available options.

==== Export sent messages

`./gmail-exporter export SENT`

==== Export messages from trashcan as EML 

`./gmail-exporter export --save-eml TRASH`

==== List available labels

`./gmail-exporter labels`

==== Fine-tune paging

Messages are downloaded in blocks (pages): set the size of each block to max 50 messages +
`gmail-exporter --page-size 50 TRASH`

Read at max 200 pages of messages +
`gmail-exporter --pages-limit 200 TRASH`


==== Throttling

Limit the transfer of messages at 1 per second +
`gmail-exporter --messages-per-sec 1 TRASH`

Limit the download of attachments at 5 per second +
`gmail-exporter --attachments-per-sec 5 TRASH`


==== Batch mode

Prevent both opening the browser window for auth and eventually writing the obtained token
`gmail-exporter --batch TRASH`


=== Authentication

When the application launches, it requests that the user grant access to data in the relevant Google account.

If the user consents, the application requests and receives a temporary token to access Gmail
data. All the exchanged data is just kept within the user local system.

The temporary token is long-lived and saved into your local folder (by default within file _token.json_).

[[token-json]]The auth token file is structured as follows

.token.json
[source,json]
----
{
  "access_token": "...",
  "token_type": "Bearer",
  "refresh_token": "...",
  "expiry": "2022-07-17T13:30:07.560873398+02:00"
}
----

== Other tools

Here are a few alternatives that are worthy of consideration:

* https://github.com/gaubert/gmvault[gmvault]
* https://github.com/GAM-team/got-your-back[got-your-back]
* https://github.com/joeyates/imap-backup[imap-backup]


== How to build

Clone the project and run +
`go build`

== How to release

Add a tag with proper message and push it
```
git tag v0.0.1 -m "First public release for wider testing."
git push origin v0.0.1 
```

== Copyright and License

Copyright (C) 2022-present Davide Cavestro.
Use of this software is granted under the terms of the MIT License.

See the {url-license}[LICENSE] for the full license text.

Documentation

Overview

gmail-exporter document