SEODrafts

Contentful SEO content publishing with field mapping

The Contentful adapter writes to the Content Management API instead of bypassing your content model. It localizes mapped fields, uses a deterministic entry ID based on the article slug, respects entry versions during updates, and publishes only when the run is explicitly in publish mode.

Best for: Headless websites that already render a Contentful content type and want reviewed SEO content to enter the same model and deployment path as editor-created entries.

Support status: stable
Publisher: contentful

How the connection works

Authentication

A Contentful Management API token scoped to the destination space, plus the Space ID, environment, content type, and locale held in the server-side publisher.

Server-side variables

  • SEO_BLOG_PUBLISH_TOKEN
  • SEO_BLOG_SITE_SLUG
  • CONTENTFUL_MANAGEMENT_TOKEN
  • CONTENTFUL_SPACE_ID
  • CONTENTFUL_ENVIRONMENT_ID
  • CONTENTFUL_CONTENT_TYPE
  • SEO_BLOG_SITE_ORIGIN

Publishing sequence

01

Build a deterministic entry ID from the reviewed article slug.

02

Map content fields and wrap values in the configured Contentful locale.

03

Read the current entry version before creating or replacing the entry.

04

Publish the saved version only in publish mode and retain the tenant-derived public URL.

No-write payload and mapping preview

SEO_BLOG_PUBLISH_TOKEN='<tenant-token>' \
SEO_BLOG_SITE_SLUG='<slug>' \
CONTENTFUL_MANAGEMENT_TOKEN='<contentful-management-token>' \
CONTENTFUL_SPACE_ID='<contentful-space-id>' \
CONTENTFUL_ENVIRONMENT_ID='<contentful-environment-id>' \
CONTENTFUL_CONTENT_TYPE='<contentful-content-type>' \
SEO_BLOG_SITE_ORIGIN='<origin>' \
npx --yes @wotaso/seo-blog-admin-cli publish-cms --cms contentful --site-slug '<slug>' --site-origin '<origin>' --dry-run

For a currently due approved post, --dry-run builds the destination payload without writing to the provider. It does not contact the provider or prove credentials, remote schema compatibility, deployment, or a live page; when no post is due, provider inputs are not exercised.

Scheduled runner health heartbeat

SEO_BLOG_PUBLISH_TOKEN='<tenant-token>' \
SEO_BLOG_SITE_SLUG='<slug>' \
CONTENTFUL_MANAGEMENT_TOKEN='<contentful-management-token>' \
CONTENTFUL_SPACE_ID='<contentful-space-id>' \
CONTENTFUL_ENVIRONMENT_ID='<contentful-environment-id>' \
CONTENTFUL_CONTENT_TYPE='<contentful-content-type>' \
SEO_BLOG_SITE_ORIGIN='<origin>' \
SEO_BLOG_SCHEDULED='true' \
npx --yes @wotaso/seo-blog-admin-cli health --config seo-blog.config.json --mode cms --site-slug '<slug>' --site-origin '<origin>'

Run this from the real scheduled runner after seo-blog.config.json contains the selected connector configuration and the listed secrets are loaded. It reports configuration readiness, not a live article. The dashboard expires readiness at the returned deadline, with a 36-hour fallback when no deadline is available.

Fields and data model

  • Field names can be overridden with an explicit field map
  • Localized values use the configured CMS locale
  • HTML body, excerpt, metadata, canonical, and social image are available

Canonical and route

The frontend consuming Contentful owns routing, canonical markup, rendering, sitemap output, and deployment. The adapter needs the production site origin because a Contentful entry ID is not a public page URL.

Known limits

  • The configured content type must contain compatible fields or an explicit field map.
  • The management token needs access to the selected space and environment.
  • Publishing an entry does not prove that the frontend deployment has completed.

Recovery

  • Start in draft mode and inspect the localized entry fields.
  • On version conflicts, reread the current entry instead of retrying with a stale version.
  • Verify the frontend route and deployment before accepting the derived public URL.

Integration questions

Where are credentials stored?

The Contentful credentials stay in CI or another server-side secret environment.

Does SEODrafts own the canonical URL?

No. The destination website owns its route, canonical tag, sitemap, rendering, and analytics.

Can the integration be tested before publishing?

Use the no-write payload preview to inspect local mapping, then separately test credentials and the first destination draft before a live run.

Keep the website your team already owns.

Review the opportunity and draft in SEODrafts, then publish approved work through Contentful.

Add my website