> For the complete documentation index, see [llms.txt](https://docs.feedotter.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.feedotter.com/newsletters/content-sources/contentful.md).

# Contentful

## Add a Contentful Content Source

A **Contentful** content source pulls entries of one content type, such as your articles or blog posts, from a Contentful space into FeedOtter. You can then add those entries to curated newsletters, the same way you add posts from RSS or WordPress.

Setting up the source takes four screens, which are tabs in the content source editor:

1. **Details:** connect to your Contentful space and choose the content type.
2. **Fields:** choose which Contentful field fills each part of a post, like the title, image and date.
3. **Filters:** optionally limit which entries come in, by tag, linked entry or date.
4. **Preview:** check a sample of entries before you use the source.

The whole process takes about 10 minutes.

{% hint style="info" %}
Every Contentful content model is different, so FeedOtter doesn't guess which of your fields to use. It only fills a row in for you when a field's ID matches the row's name exactly. For example, a field with the ID `title` fills the **Title** row. Check each row on the **Fields** tab before you save.
{% endhint %}

### Before you start

You'll need, from Contentful:

* **Your space ID.**
* **An access token:**
  * a **Content Delivery API** token if newsletters should only include published entries, or
  * a **Content Preview API** token if they should include drafts as well.
* **Your environment ID**, if your content isn't in the default `master` environment.
* **Your space's region:** US (the default) or EU, if your space uses EU data residency.

You'll also need **your website's article URL pattern**, for example `https://www.example.com/blog/{slug}`. Contentful doesn't store the public web address of an entry, so FeedOtter builds each post's link from this pattern.

#### Find your space ID and token in Contentful

1. In Contentful, open **Settings → API keys**.
2. Open an existing API key, or click **Add API key** to create one for FeedOtter.
3. Copy the **Space ID**, and either the **Content Delivery API – access token** or the **Content Preview API – access token**.

### Step 1: Start a new content source

1. In FeedOtter, go to **Content → Content Sources**.
2. Click **Add Content Source**.

The **Create Content Source** editor opens on the **Details** tab.

### Step 2: Details

#### Source

| Field           | What to enter                                                      |
| --------------- | ------------------------------------------------------------------ |
| **Name**        | A name your team will recognize, e.g. `Blog articles (Contentful)` |
| **Source Type** | `Contentful`                                                       |
| **Groups**      | Optional. Add the source to one or more content source groups      |

#### Contentful Space

| Field            | What to enter                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **Space ID**     | Your space ID from Contentful                                                              |
| **Environment**  | `master`, unless your content is in another environment                                    |
| **API**          | **Delivery (published only)** or **Preview (includes drafts)**. This must match your token |
| **Region**       | **US (default)** or **EU**                                                                 |
| **Access token** | The Delivery or Preview token that matches the **API** you chose                           |
| **Site URL**     | Your article URL pattern. See Site URL below                                               |

Click **Connect**. When the connection works, you'll see **Connected.** and FeedOtter loads your content types, locales and tags. If it fails, the message tells you why. Check that the space ID, environment, region and API all match your token.

**Site URL**

FeedOtter builds each post's link from the **Site URL**:

* **A URL with placeholders**, for example `https://www.example.com/news/{slug}`. Each `{...}` is replaced with that field's value on the entry. Use `{slug}`, `{id}` (the entry ID), or any field ID in braces.
* **A plain URL**, for example `https://www.example.com/news`. FeedOtter adds the entry's `slug` field to the end.

If an entry has no value for a placeholder, that post has no link.

#### Settings

| Field            | What to enter                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------- |
| **Content type** | The content type to pull in, e.g. `Blog Post (blogPost)`                                    |
| **Status**       | Only shown for the Preview API. Choose **Published**, **Draft**, or leave it empty for both |
| **Max posts**    | How many of the newest entries to fetch, from 1 to 500. Default: 25                         |
| **Locale**       | **Space default**, or another locale your space uses                                        |

{% hint style="info" %}
With the Preview API, **Draft** means never published. A published entry that has unsaved changes counts as **Published** and shows its latest, unpublished content. Archived entries are never included.
{% endhint %}

### Step 3: Fields

The **Fields** tab decides which Contentful field fills each part of a FeedOtter post. The dropdowns list the fields found on your content type's recent entries, including fields of linked entries and images, e.g. `fields/heroImage/url` or `fields/author/fields/name`.

#### Standard rows

| Row             | What to choose                                                       | If left empty                                                                 |
| --------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Title**       | The entry's headline field, e.g. `fields/title`                      | The content type's display field (the one Contentful uses as the entry title) |
| **Description** | A short summary field, e.g. `fields/summary`                         | A field with the ID `description`, if there is one                            |
| **Content**     | The article body, e.g. `fields/body`. Rich text is converted to HTML | A field with the ID `content`, if there is one                                |
| **URL**         | Usually leave empty. See below                                       | The link built from your **Site URL**                                         |
| **Date**        | The date for each post. See Date below                               | Can't be empty                                                                |
| **Image URL**   | The image to show, e.g. `fields/heroImage/url`                       | No image                                                                      |

**URL:** leave this empty to use your **Site URL** pattern or map it to the "url" field if you have one.

**Date**

The **Date** row controls everything date-related for this source:

* the date shown on each post,
* the order entries come in (newest first), and
* the **Only include entries from the last N days** filter on the **Filters** tab.

Choose one of:

* **Publish date (sys/createdAt)**, the default: when the entry was first published. With the Preview API, it's when the entry was created.
* **Last updated (sys/updatedAt)**
* any **Date** field on your content type, e.g. `Publish Date (fields/publishDate)`

If an entry has no value in the chosen field, its post has no date.

#### Custom mappings

Click **Add new custom data mapping** to bring in any other field. Give it a **Name**, choose the field path, and pick a **Type** (Text, Rich Text, Image, URL or Date). The value is then available to your templates as a custom field under that name.

#### If a field isn't listed

The list comes from your most recent entries. If a field is empty on all of them, mostly fields inside linked entries, it may not appear:

* Click **Reload fields** after adding content in Contentful, or
* tick **Type paths manually** and type the path, e.g. `fields/heroImage/url` or `fields/author/fields/name`.

### Step 4: Filters (optional)

Leave everything empty to include all entries of your content type.

| Section            | What it does                                                                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tags**           | Only include entries with **any** of the selected tags. Only public Contentful tags are listed                                                      |
| **Linked Entries** | Only include entries whose chosen reference field links to any of the selected entries. For example, a `category` field and the categories you want |
| **Date Filters**   | **From the last N days** only includes entries whose **Date** row value falls in that window. **Any date** includes everything                      |

If a reference field can link to any content type, FeedOtter can't list its entries. Paste the entry IDs instead, separated by commas. You'll find an entry's ID in Contentful under **Info**.

### Step 5: Preview and save

1. Open the **Preview** tab and click **Generate Preview**. This saves your settings and fetches a sample of 10 entries.
2. Check the sample:
   * **Cards** shows each post as it will look: title, image, excerpt and link.
   * **Fields** lists every value, which helps when a mapping looks wrong.
3. If something is missing or wrong, go back to **Fields** or **Filters**, change it, and click **Refresh Preview**.
4. Click **Add Source**.

The **Add Source** button is available once you've entered a **Name**, **Space ID**, **Access token**, **Content type** and a valid **Site URL**. FeedOtter checks the connection to Contentful when you save.

### Use the source in a newsletter

In a curated newsletter, choose your Contentful source under **Available Content**. You can search its entries, and more load as you scroll. Add entries to your newsletter like posts from any other source.

If you edit a post in the newsletter, the **Revert to original** button (the restore icon in the post's edit panel) puts back the values from your field mappings.

### Troubleshooting

| Problem                                              | What to check                                                                                                                      |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Connect** fails                                    | The space ID, environment, region and API must all match your token. A Preview token only works with **Preview (includes drafts)** |
| No content types listed                              | The token's API key must have access to the environment you entered                                                                |
| "No fields were found" on the Fields tab             | Check the content type on the **Details** tab, or tick **Type paths manually**                                                     |
| Posts have no link                                   | Each entry needs a value for every placeholder in your **Site URL**, e.g. `{slug}`                                                 |
| Posts have no date, or the date filter drops entries | Entries need a value in the field chosen in the **Date** row                                                                       |
| Posts have no image                                  | Map the **Image URL** row to an image path, e.g. `fields/heroImage/url`                                                            |
| Drafts are missing                                   | Use **Preview (includes drafts)** with a Content Preview API token, and check **Status**                                           |
