How to Export Gmail to JSON for Developers

Export formats

Gmail Exporter Guide

If you are feeding email into a script, a notebook, or a data pipeline, JSON is usually the format you actually want. CSV is fine for a spreadsheet, but the moment you need to iterate over records, filter on fields, or hand the data to another program, a JSON array of objects is cleaner to work with. This guide covers how to produce that file, what the schema looks like, and how to parse it in the languages you are most likely using.

Why JSON over CSV for code

CSV is flat: every value is a string and the structure is implied by column position. That is great for Excel and Google Sheets, but it forces awkward escaping whenever a field contains commas, quotes or line breaks — and email bodies contain all three constantly. JSON encodes types and nesting explicitly, so a body with newlines stays a single clean string, and you never have to guess where one record ends and the next begins. For programmatic work, JSON simply removes a class of parsing bugs. If you specifically need a spreadsheet instead, see exporting Gmail to CSV.

How to produce the JSON file

1. Install a local exporter. Add Gmail Exporter to Chrome. It runs in your browser, so no API keys or OAuth setup are required just to get a dataset.
2. Scope the data with Gmail search. Use operators such as from:, label:, after: and has:attachment so the export contains exactly the subset you want to process.
3. Export and choose JSON. The file is written straight to your downloads folder.
4. Load it in your environment. Open it in your script, notebook, or pipeline step like any other JSON file.

Because everything happens locally, the message contents are never sent to an outside server before you have the file. That matters when you are prototyping against real correspondence rather than synthetic data.

The field schema

A Gmail JSON export is a flat array. Each element is one message. The exact keys depend on your plan, but the shape is consistent:

Example record

[
  {
    "email": "maria@acme.com",
    "name": "Maria Lopez",
    "subject": "Q3 proposal follow-up",
    "body": "Hi, thanks for the call earlier...",
    "date": "2026-06-18T14:22:00",
    "service": "acme.com",
    "direction": "received"
  }
]

Parsing the file

Python

import json

with open("gmail-export.json") as f:
    messages = json.load(f)

# count emails per sender
from collections import Counter
top = Counter(m["email"] for m in messages)
print(top.most_common(10))

Node.js

const fs = require("fs");
const messages = JSON.parse(fs.readFileSync("gmail-export.json", "utf8"));

const recent = messages.filter(m => m.date > "2026-01-01");
console.log(recent.length, "messages this year");

Command line with jq

jq '[.[] | {email, subject, date}]' gmail-export.json

Common developer use cases

• Feed an analysis script. Aggregate volume by sender or month, then drop the result into a sheet as covered in exporting Gmail to Excel.
• Seed a database. Map each record onto a row and bulk-insert into Postgres or SQLite.
• Build a contact graph. Extract every unique address to reconstruct who you talk to, similar to extracting all email addresses from Gmail.
• Train or test on real text. Use the body field as input for a classifier or a search index.

Handling large inboxes

JSON file size grows with both the message count and how much body text you keep. A few thousand messages with snippets typically lands in the low single-digit megabytes. If you are working with a very large account, export per label or per date range rather than one enormous file, then process the parts in a loop. If you need a complete archive of everything rather than a working dataset, a JSON export is not the right tool — read how to back up your entire Gmail inbox for the archival options.

A note on privacy and ethics

Exported email often contains other people's personal data. If your script stores or shares the JSON, treat it like any other dataset of personal information: keep it local where possible, delete it when you are done, and respect the consent and lawful-basis rules that apply to you. Our contacts extraction guide covers the practical compliance side in more depth.