Adding data feeds in Letterhead

A data feed fills your Curations library from any JSON API — product listings, event schedules, sports scores, headlines, anything an endpoint returns as a list. Connect the API once, tell Letterhead which parts of each item map to a title, a link, and the rest of your curation fields, and its items flow into your library like any other curated content: ready to drop into a newsletter, deduplicated, and refreshed for you on a schedule. It’s the hands-off way to pull a source that isn’t an RSS feed.

Note

This is Letterhead’s own data feed, feeding your Curations library for newsletters you send through Letterhead. It’s separate from connecting an external ESP’s data feeds, which is about a provider like Iterable resolving its own feeds at send time.

Before you add a data feed

• Check the response shape — the URL must return JSON containing an array of items (for example, a list of products or articles). Open it in a browser and confirm you get back a list, not a single object.
• Use a secure address — the feed URL must be https://. Letterhead won’t fetch a plain http:// address or one that points at a private or internal network.
• Have a credential ready if the API needs one — if the endpoint requires authorization to respond, have its bearer token on hand. You’ll paste it once; Letterhead stores it encrypted and never shows it again.

Add a data feed

1. Open Curations and go to the Data Feeds tab.
2. Click Add Data Feed and give it a Title, a Description, and the API URL.
3. Under Authorization, choose None if the API is public, or Bearer token and paste the token if it needs one.
4. Letterhead fetches a live sample from the URL so you can map against real data. If the fetch fails, fix the URL or credential and try again before mapping.
5. Map the fields (see below), then save.

After you save, Letterhead begins pulling the feed, and its items should start appearing in your library within a few minutes — from then on it refreshes on the same regular schedule as your other feeds.

Map the API’s fields to your curation fields

Mapping is how Letterhead turns one of the API’s items into a curation. For each Letterhead field, pick the part of the item that fills it. You’ll choose from the fields found in the live sample, and each Letterhead field is mapped once.

• A title, an excerpt, and a link are required — the same essentials every curated story needs. The link is also how Letterhead recognizes an item it has seen before, so each item needs its own unique URL.
• An image and your custom curation fields are optional — map them when the feed carries them, leave them unset when it doesn’t.
• Reach values nested inside an item — when a value lives inside a nested object or a list rather than at the top level, you can still map to it. Letterhead surfaces the first few entries of a list so you can pick one directly (for example, the first image in a gallery); to reach a deeper position, type the path by hand and Letterhead will follow it.

If an item is missing one of the required fields, Letterhead skips just that item and keeps the rest, so one incomplete entry never blocks the feed.

How Letterhead keeps a data feed fresh

A data feed behaves like an RSS feed once it’s connected:

• It refreshes automatically on a regular schedule, pulling new items as the API’s data changes.
• Duplicates are filtered by each item’s link, so re-fetching the same list doesn’t clutter your library.
• A feed that keeps failing is marked invalid — after repeated errors Letterhead stops checking it and shows the last error, until you revalidate it.

Recover a data feed that’s stuck

The Data Feeds tab gives you the same two recovery actions as the RSS list, on any feed’s row:

• Revalidate — a one-click action on a feed that’s gone invalid. It clears the error state and puts the feed back in line to be fetched. Fix the underlying problem first — a wrong URL or an expired token — or the next fetch will just fail again.
• Reset — makes Letterhead treat the feed as brand new and re-pull every item it returns, regardless of age or whether the item has appeared in past newsletters. Useful when a feed was broken or its data changed shape. Large feeds take a while and previously used items may reappear, so Letterhead asks you to confirm first.

Tip

Once a data feed’s items are in your library, they behave like any other curation — search them, tag them, and drop them into a newsletter exactly as you would a hand-picked story.