# Contentful

## Contentful Integration

Connect Cuppa to Contentful to automatically export your AI-generated content directly to your Contentful space. This integration is ideal for teams using Contentful as a headless CMS with React, Next.js, Gatsby, or other frontend frameworks.

### What You Can Do

* **Export projects** to Contentful with one click
* **Map your fields** to match your Content Type structure
* **Auto-publish entries** or keep them as drafts for review
* **Bulk export** with built-in rate limiting

***

### Prerequisites

Before connecting, you'll need:

1. A **Contentful account** and space
2. Your **Space ID** and **Environment ID**
3. A **Personal Access Token (CMA)** with write access

***

### Step 1: Get Your Contentful Credentials

#### Find Your Space ID

1. Log in to [Contentful](https://app.contentful.com)
2. Go to **Settings** → **General settings**
3. Copy your **Space ID**

#### Find Your Environment ID

1. Go to **Settings** → **Environments**
2. Usually this is `master` for production
3. Note the environment ID you want to export to

#### Create a Personal Access Token

1. Click your avatar → **Settings**
2. Go to **CMA tokens** tab
3. Click **Generate personal token**
4. Give it a descriptive name (e.g., "Cuppa Integration")
5. **Copy the token immediately** — you won't see it again!

> **Important**: Personal Access Tokens provide full access to your space. Keep them secure and never share them publicly.

***

### Step 2: Set Up Your Content Type

Ensure you have a Content Type in Contentful to receive your articles. A typical blog post Content Type might have:

| Field Name      | Field Type  | Description                  |
| --------------- | ----------- | ---------------------------- |
| `title`         | Short text  | Article title                |
| `slug`          | Short text  | URL slug                     |
| `body`          | Long text   | Main article content         |
| `description`   | Short text  | Meta description/excerpt     |
| `publishedDate` | Date & time | Publication date             |
| `featuredImage` | Media       | Featured image (URL as text) |

#### Finding Field IDs

Field IDs are what you'll use for mapping. To find them:

1. Go to **Content model** in your space
2. Click on your Content Type (e.g., "Blog Post")
3. Click on a field to see its **Field ID** (not the display name)

> **Note**: Field IDs are case-sensitive and usually lowercase (e.g., `title`, `slug`, `body`).

***

### Step 3: Connect Contentful in Cuppa

1. Go to **Team Settings** → **Integrations**
2. Find **Contentful** and click **Connect**
3. Enter your **Space ID**, **Environment**, and **Personal Access Token**
4. Click **Load Types** to fetch your Content Types
5. Select your target **Content Type** (e.g., "Blog Post")
6. Set your **Locale** (e.g., `en-US`)
7. Toggle **Auto-publish entries** if you want entries published immediately
8. **Map your fields**: Tell Cuppa which Contentful field IDs should receive each content field
9. Click **Connect**

***

### Step 4: Export Content to Contentful

#### Export a Single Project

1. Open any project in Cuppa
2. Click the **"Export"** dropdown
3. Select **"Export to Contentful"**
4. Choose which articles to export (or export all)
5. Click **Export**

#### What Happens During Export

For each article, Cuppa:

1. Creates a new entry in your Contentful space
2. Maps your configured fields to the entry
3. Optionally publishes the entry (if auto-publish is enabled)

***

### Field Mapping Reference

When setting up your integration, you map Cuppa fields to your Contentful field IDs:

| Cuppa Field      | Description           | Recommended Contentful Field Type |
| ---------------- | --------------------- | --------------------------------- |
| `title`          | Article title         | Short text                        |
| `slug`           | URL-friendly slug     | Short text                        |
| `content`        | Full HTML content     | Long text (HTML)                  |
| `excerpt`        | Short summary         | Short text or Long text           |
| `target_keyword` | Primary keyword       | Short text                        |
| `language`       | Content language      | Short text                        |
| `image`          | Featured image URL    | Short text (URL)                  |
| `date`           | Article creation date | Date & time                       |
| `model`          | AI Model used         | Short text                        |
| `pov`            | Point of View         | Short text                        |
| `tone`           | Tone of Voice         | Short text                        |

#### Important Notes on Field Types

* **Rich Text fields**: Contentful's Rich Text requires a specific JSON format. For simplicity, map `content` to a **Long text** field with HTML rendering, not Rich Text.
* **Media/Asset fields**: Cuppa exports image URLs as strings. To use Contentful's Media field type, you'd need to upload assets separately.
* **Locales**: Entries are created with the locale you configure. Multi-locale support is not currently available.

***

### Troubleshooting

#### "Connection failed" or "Access denied"

* Double-check your Space ID, Environment ID, and Access Token
* Ensure your token hasn't expired
* Verify the token has write access (CMA tokens, not CDA)

#### "Content type not found"

* Click **Load Types** to refresh the content type list
* Ensure the content type exists in the selected environment
* Check that the environment ID is correct (e.g., `master` vs `staging`)

#### "Field validation failed"

* Check that your field mapping uses correct field IDs (case-sensitive)
* Ensure mapped fields exist in your Content Type
* Verify field types match (e.g., don't map long content to Short text with a 256 char limit)

#### Entries created but not visible

* Check if auto-publish is enabled; if not, entries are drafts
* Go to **Content** in Contentful and filter by status: "Draft"
* Verify entries are in the correct environment

#### Rate limit errors

* Contentful CMA has a rate limit of 10 requests/second
* Cuppa handles this automatically with built-in delays
* For very large exports, the job may take longer but will complete

#### Content appears with HTML tags

* This happens when mapping HTML content to a plain text field
* Use **Long text** fields with HTML rendering enabled
* Alternatively, configure your frontend to render HTML safely

***

### FAQ

**Can I export to multiple Contentful spaces?** Currently, each Cuppa team can connect to one Contentful space. Update your integration settings to switch between spaces.

**Does it update existing entries or create new ones?** Cuppa creates new entries each time. If you need to update existing entries, delete them in Contentful first.

**Can I export to Rich Text fields?** Rich Text in Contentful requires a specific JSON format. For simplicity, we recommend using Long text fields with HTML content. Future updates may support Rich Text conversion.

**Why isn't my featured image showing?** Cuppa exports image URLs as strings. Contentful Media fields require asset uploads. Map images to a Short/Long text field and handle the URL in your frontend.

**What happens if an export fails midway?** Cuppa exports entries one at a time with error handling. Successfully created entries remain in Contentful. Failed entries are logged and you can retry the export.

**How do I know which locale to use?** Check your Contentful space's **Settings** → **Locales**. Common values are `en-US`, `en-GB`, `de-DE`. Use the locale code, not the display name.

**Can I auto-publish entries?** Yes! Enable "Auto-publish entries" in your integration settings. Otherwise, entries are created as drafts.

***

### Need Help?

* Check our [Help Center](https://learn.cuppa.ai)
* Contact support at <support@cuppa.ai>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/integrations/contentful.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.