Help

Contentful Integration

Connect BlogSEO to your Contentful space to automatically publish AI-generated articles to any content model, with AI-driven mapping of your fields, full Rich Text rendering, and asset uploads to your Contentful library.

Requirements

Before connecting Contentful, make sure you have:

  • A Contentful account with access to at least one space.
  • Admin permissions on the space you want to connect. Admin rights are required for OAuth scope approval and webhook creation.
  • A content model for your blog articles (for example blogPost, pageBlogPost, article).
  • The content model must include at least one Rich Text field. BlogSEO publishes the article body into a Rich Text field, and the integration will refuse to publish without one.

Installation

The integration uses Contentful's OAuth flow, so there is no API token to copy or store anywhere. The full setup takes less than a minute.

  1. In your BlogSEO dashboard, open Integrations → Contentful.
  2. Click Connect Contentful. You are redirected to Contentful's authorization page.
  3. Make sure you are logged in to the correct Contentful account, then approve the content_management_manage scope. This is the scope BlogSEO needs to read your content models, create entries and assets, and register the sync webhook.
  4. Contentful redirects you back to BlogSEO with the connection in place. BlogSEO automatically:
    • Fetches all your organizations, spaces, and content models.
    • Picks a primary space (the first one returned by Contentful).
    • Picks the most appropriate content model for blog articles using AI, based on the field structure of each model.
    • Creates a signed webhook in Contentful for two-way sync.
  5. On the integration page, review the auto-selected Organization, Space, and Content Model. If the AI guess is wrong, click Update Configuration to switch to a different one.
  6. If your content model has more than one Rich Text field, pick which one BlogSEO should publish the article body into.
  7. Toggle Auto-publish on if you want generated articles to be pushed to Contentful as soon as they are produced.

The OAuth token is encrypted at rest. You can revoke BlogSEO's access at any time from your Contentful account settings under OAuth Tokens, but doing so will silently break publishing. Reconnect from BlogSEO to restore the integration.

Recommended Content Model

The integration is built to adapt to whatever content model you have, but a clean blog content model gives the AI mapper much better results.

At a minimum, your content model needs:

  • A Rich Text field for the article body.

For high-quality publishing, we recommend the following fields:

  • title (Short text / Symbol). Used for the article headline.
  • slug (Short text / Symbol). Used for the URL.
  • shortDescription or excerpt (Short text / Long text). Used for the meta description and article preview.
  • featuredImage (Media → one Asset). Receives the article's main image. BlogSEO downloads the image from its own storage and uploads it as a Contentful Asset.
  • content (Rich Text, required). Receives the article body, with inline images uploaded as Contentful Assets and embedded as embedded-asset-block nodes.
  • publishedDate (Date & time). Filled by BlogSEO at publish time.
  • seoFields (Reference to a small componentSeo model with metaTitle, metaDescription, optional ogImage, noIndex, noFollow). Linked references like this one are filled in automatically (see below).
  • author (Reference to a componentAuthor model with name, avatar, shortBio).

This is exactly the content model that powers the BlogSEO landing page blog, which is itself built on Contentful. If you want a working reference, model your pageBlogPost content type on:

internalName: Symbol (required)
seoFields: Reference → componentSeo
slug: Symbol (required)
author: Reference → componentAuthor
publishedDate: Date
title: Symbol (required)
shortDescription: Symbol
featuredImage: Asset (required)
content: RichText (required)
relatedBlogPosts: Array of Reference → pageBlogPost

Field Mapping

Field mapping is fully automated, no manual configuration is needed. Once a content model is selected, BlogSEO fetches its schema on every publish and decides what to put in each field based on field type, field name, and the article being published.

Rich Text body

The Rich Text field you selected during installation receives the article body. The article markdown is converted to Contentful's Rich Text format, including headings, lists, links, code blocks, and inline images. Inline images are downloaded from BlogSEO storage, uploaded as Contentful Assets, and inserted as embedded-asset-block nodes inside the Rich Text document.

If your content model has a single Rich Text field, BlogSEO uses it. If it has several, you pick one explicitly in the configuration modal.

Main image (Asset link)

If your content model has exactly one Asset link field (or several Asset links with exactly one marked required), BlogSEO uploads the article's main image into your Contentful Asset library and links it to that field. On updates, the existing asset is replaced in place to avoid orphans.

Scalar fields (title, slug, SEO, etc.)

For every other field on the content model (Symbol, Long text, Integer, Number, Date, Boolean, Location, Object, Array of scalars), BlogSEO uses an LLM with structured output:

  1. The Contentful schema for the content type is converted into a JSON Schema that mirrors each field's type and required flag.
  2. The LLM receives the article (headline, markdown, summary, keywords), the website context, and an existing entry from your space as a few-shot example.
  3. The LLM returns a JSON object that strictly matches the schema. BlogSEO writes the response into the new Contentful entry.

This is why the integration is flexible: you can add or rename fields in your Contentful model and BlogSEO will keep mapping them correctly on the next publish. The richer your field names (metaTitle instead of field1), the better the mapping.

Linked entries

If your content model has fields that link to other entries (single Reference or array of References, like seoFields linking to a componentSeo), BlogSEO handles them recursively:

  1. For each Reference field, the AI checks whether an existing entry in your space already fits the article. If yes, it links to it.
  2. If no existing entry matches, a new entry is created in the linked content type. The same mapping logic runs again on that nested entry, up to a recursion depth of 3.
  3. If the AI decides nothing makes sense to fill, optional Reference fields are skipped.

This is what makes models like the recommended one above work end-to-end: the seoFields and author references are populated automatically without you having to maintain them by hand.

Localization

The article is published into the default locale of the selected environment. Other locales need to be created from inside Contentful. The webhook sync (see below) reads the default locale only.

Headless CMS Disclaimer

Contentful is a headless CMS. It stores your content as structured JSON, but it does not render anything. BlogSEO's job stops at writing well-formed entries, assets, and Rich Text into your space.

How that content is fetched, parsed, and rendered on your website is entirely the responsibility of your frontend code. If a published article looks wrong on your website (broken layout, missing images, missing fields), the issue is on the rendering side, not in BlogSEO. Common things to check on your end:

  • Your frontend queries the right content type and locale.
  • Your Rich Text renderer handles embedded-asset-block nodes and resolves the linked Asset URLs.
  • Your frontend resolves linked entries with a sufficient include depth (Contentful defaults to 1, you usually want 2 or more).
  • Your image rendering resolves protocol-relative Contentful asset URLs (they start with //).

The Contentful renderer used on our own landing site is a good starting point if you are building this from scratch.

Publishing

Two ways to push articles to Contentful:

  1. Auto-publish: enable the toggle on the integration page. BlogSEO pushes each new article to Contentful as soon as generation finishes.
  2. Manual publish: open any generated article and click Publish to send it on demand.

Updating an article in BlogSEO and re-publishing updates the existing Contentful entry in place (Rich Text body, title, and main image asset are refreshed) instead of creating a duplicate.

Two-Way Sync

When the OAuth flow completes, BlogSEO creates a Contentful webhook in your space, scoped to your selected content model and environment. The webhook is HMAC-signed using a secret stored only in your connection, and listens for Entry.publish, Entry.unpublish, and Entry.save events.

When you edit an entry in Contentful that was originally created by BlogSEO:

  • On publish: the article status in BlogSEO is set to published.
  • On unpublish: the article status is set back to preview.
  • On save: the Rich Text body is converted back to markdown (via the HTML renderer + Turndown) and synced into BlogSEO's copy of the article, so future regenerations stay in sync with your edits.

The webhook is created and removed automatically when you connect or disconnect the integration. There is nothing to configure on Contentful's side.

Troubleshooting

Connection fails during OAuth

  • Make sure you are logged in to Contentful in the same browser before clicking Connect Contentful.
  • You need admin access to the space, otherwise Contentful blocks the webhook creation step and the connection fails.
  • If your organization restricts OAuth apps, ask an organization owner to approve BlogSEO.

Articles not publishing

  • No Rich Text field: confirm the selected content model has at least one Rich Text field. Long text and Markdown fields are not supported as the article body.
  • Required field BlogSEO cannot fill: if your model has a required field that the AI cannot infer (for example, a required Reference to a content type that does not exist yet), publishing fails. Either make the field optional or pre-create at least one entry of the linked content type so the AI has something to link to.
  • Multiple Rich Text fields: if you have more than one Rich Text field and none is selected, publishing fails. Pick one in the configuration modal.

Images not uploading

  • Asset permissions: the connected Contentful user needs permission to create and publish assets in the space.
  • Image URL accessibility: BlogSEO passes the image URL to Contentful, which downloads it server-side. If the URL is behind authentication or has expired, the upload fails and the field is left empty.

Linked references stay empty

  • The AI skips optional Reference fields when it has no good candidate entry to link to and no clear way to create one. To force population, pre-create one example entry in the linked content type with all fields filled in. The AI will then either reuse it or use it as a template.

Connection lost after revoking access

If you revoke BlogSEO from your Contentful account settings, the integration silently stops working. Reconnect from your BlogSEO dashboard to restore it.

For additional support, contact our team through the in-app chat or at support@blogseo.io.

Was this page helpful?