Send a daily data export to your Amazon S3 bucket

Overview

If your data team wants Letterhead data in its own warehouse, you don’t have to call the API to get it. Connect an Amazon S3 bucket that you own, and Letterhead saves a fresh set of JSON files there every morning. Most warehouses can load straight from S3.

Each day’s export has three parts:

• Contacts — your whole audience as it stands that morning: profile fields, custom fields, subscriptions, and tags.
• Newsletters — the newsletters you sent the day before, with the channel, title, subtitle, and send time.
• Message events — everything that happened to your newsletters the day before: sent, opened, clicked, bounced, and unsubscribed. Each row has the reader’s email address, the time, and the newsletter it belongs to, plus the link for a click and the bounce type for a bounce.

The export carries simple engagement signals and tags only. It leaves out Letterhead’s own analysis of your audience, such as inferred interests and health scores, as well as spam complaints. To get totals such as opens per contact, add up the message events in your warehouse.

Before you start

• You need an Amazon S3 bucket and an access key that can write to it. Create an IAM user for Letterhead and give it only the s3:PutObject permission on that one bucket (and folder, if you use one). Letterhead never needs to read or delete anything.
• Connecting integrations is an administrator task. If you don’t see the option, ask a company administrator.

How to connect

1. Go to Integrations in your company settings.
2. Find the Daily data export to Amazon S3 card and open it.
3. Enter your Access key ID, Secret access key, Region (for example us-east-1), and Bucket name.
4. Optionally enter a Folder. Files are saved inside it.
5. Choose Connect bucket.

Letterhead writes a small test file, letterhead-connection-check.json, to the bucket to make sure the key works. You can ignore or delete it; it isn’t part of your data. If it can’t, you’ll see a message asking you to check the key, region, and bucket name.

Your secret access key is stored encrypted and is never shown again. To stop the export, open the card and choose Disconnect.

What lands in your bucket

Every morning Letterhead adds a folder named for the day, in UTC, such as 2026-10-15, inside your bucket (or your chosen folder). A folder holds:

File	What’s in it
contacts-part-0001.json, contacts-part-0002.json, …	Your contacts, up to 1,000 per file
newsletters.json	The newsletters sent the day before
events-part-0001.json, events-part-0002.json, …	The day before’s message events, up to 1,000 per file

Large audiences produce many files, so load the whole folder rather than a single file. The events file for a quiet day is still written, just empty, so once a day shows Completed, a missing events file means something went wrong. (An audience with no contacts gets no contacts file.)

Your first files arrive after the next daily export following the connection.

See each day’s export

Open the card again after you’ve connected to see Recent exports: today and the 13 days before it, or since you connected if that’s more recent. Each day shows:

• Whether it Completed, is Running, Failed, Didn’t finish, or Didn’t run.
• Which day’s activity it covers.
• When it started, and how many files and how much data it saved.
• If something stopped it, which part (contacts, newsletters, or activity) and why.

Run a missed day again

If a day failed or didn’t run, choose Run again next to it. You can re-run any of the last 14 days unless that day’s export is still running.

A re-run rewrites each file it produces in that day’s folder. If the day now produces fewer files than before, the older extra parts are left behind, so clear that day’s folder in your bucket before you reload it. Its newsletters and message events cover the original day, but the contacts file is your audience as it is now, because Letterhead doesn’t keep a history of contacts.