Skip to content
Tinbox
Sign in

Download all your Tinbox data

Create, protect, verify, and restore a portable Tinbox archive containing selected D1 rows plus retained raw messages and attachments.

Tinbox can package a deployment into one portable tar archive: selected account rows from D1 plus retained source messages and attachments from R2. Use it for an offline custody copy or a Tinbox-to-Tinbox move. It is not the same as the Gmail/IMAP/mbox/Mailchimp connectors, which parse foreign source data.

Authorization and security boundary

Creating or downloading an export requires an admin-level session with org:export_data. Restoring one is owner-only (org:import_data) because it can replace live account rows.

Treat the archive like a database backup. It is a plain, unencrypted tar and a full export can contain personal mail, attachment bytes, team access records, API-key hashes and scopes, webhook/channel endpoints, device registrations, and deployment-sealed settings. The plaintext value of a Tinbox API key is not stored, but restoring its hash can keep a separately held key usable on the destination. Store the tar encrypted at rest, share it only through a protected channel, and rotate or revoke reusable credentials around a migration according to your threat model.

The one action

Sign in as an admin, open Settings → Export / Import, and choose Create full archive. Tinbox builds it in the background. When its status changes to Ready, choose Download. Use a custom archive when you need only selected families or want to omit large raw messages and attachments.

The link is private, freshly signed, and expires. Finished archives are removed from the deployment after 48 hours, so keep the downloaded file somewhere you control.

What the tar contains

manifest.json
tables/<table>.<part>.ndjson
blobs/<number>.bin
  • manifest.json records the format version, selected data families, row totals, and the mapping from each short blob filename to its original R2 key.
  • tables/ contains newline-delimited JSON for every selected, exportable D1 table: mail, contacts, campaigns, sending history, access records, and settings.
  • blobs/ contains the original raw .eml objects and attachments. The manifest preserves their real object keys so an import restores them to the same place.

Sign-in sessions, password hashes and OAuth account tokens, verification tokens, passkeys, derived caches, and the export/import job ledger are not moved. Deployment environment secrets are outside D1 and are not present either.

That exclusion is deliberately narrower than “no credentials.” API-key rows are exported as hashes and metadata, and some account settings contain encrypted or otherwise reusable configuration. Sealed values are tied to the destination's encryption master key; do not assume a different deployment can decrypt them. Plan to re-enter integrations and Worker secrets on the destination, then rotate credentials rather than copying a master key through the archive.

Restore it

Update the destination to the same or a newer Tinbox release first. An importer refuses an archive with a newer major portability format; it tolerates newer minor metadata and filters row columns against the destination's live schema.

On a fresh Tinbox deployment, sign in as the owner, open Settings → Export / Import, and choose the tar under Import an archive. Pick the restore mode deliberately:

ModeDatabase behaviorUse it when
Keep existing rows (default)INSERT OR IGNOREFirst pass or a re-run where destination rows must win
Overwrite / mergeINSERT OR REPLACEThe archive is authoritative for colliding ids

IDs and R2 keys are preserved, and re-running the same archive converges rather than creating duplicates. Full fidelity still depends on selecting every data family and enabling raw messages and attachments; omitted families or blobs cannot be reconstructed from the archive.

Verify before cutover

  1. Keep the source deployment available until validation is complete.
  2. Compare the archive manifest totals with the completed import job.
  3. Search several old and recent threads; inspect dates, participants, read state, drafts, and sent/inbox placement.
  4. Download representative attachments and inspect an inbound raw .eml.
  5. Review members, roles, grants, sending identities, suppressions, audiences, campaigns, and settings.
  6. Re-enter destination Worker secrets and any sealed integration credentials; test sending and webhooks with safe test recipients.
  7. Revoke or rotate old API keys, webhook secrets, device/channel credentials, and temporary migration access as appropriate.
  8. Delete the server-side export job and securely remove local archive copies you no longer need. Automatic expiry is not a substitute for local cleanup.

See also