Contentful

Contentful Integration

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

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

• Contact support at [email protected]