Contentful integration
Approved work lands in Contentful, without copy-paste.
Create versioned Contentful entries with validated Rich Text and scheduled publish actions.
How it works
SearchHandled connects to Contentful through the Content Management API with a personal access token or OAuth, writing entries into your space against your content model. Body content is converted from our format into Contentful's Rich Text JSON AST and validated against your field rules before anything is sent, and assets are created and linked properly rather than referenced externally.
Entries are created unpublished, which is Contentful's natural draft state, and publishing is a separate explicit call. Scheduling uses Contentful's Scheduled Actions, so a scheduled publish lives in Contentful and fires on time regardless of our systems. Every update respects Contentful's optimistic locking: we track version numbers, and on a version conflict we re-fetch and retry rather than clobbering concurrent edits.
Best forTeams with an established Contentful content model who want entries created and published correctly against it.
Setup, step by step
- Create a personal access token in Contentful (or authorize via OAuth) with access to the target space and environment.
- Choose the content type that represents your posts, and map its fields to SearchHandled content fields.
- Run the connection check, which creates and deletes an unpublished test entry to verify permissions and field mapping.
- Set defaults for locales and whether approved entries publish immediately, on a schedule, or wait unpublished.
- Deliver a test entry and review it in the Contentful web app.
What lands in Contentful
| Element | How it lands |
|---|---|
| Title and body | Converted to the native format, then verified by reading the entry back. |
| SEO metadata | Mapped to the platform's own fields, and flagged where it has none. |
| Images | Uploaded to your media storage with alt text. Never hotlinked. |
| Internal links | Rewritten to your live URLs and checked against redirects. |
| Publish state | Draft, published, and scheduled actions. |
Field mapping is confirmed against your own content model during setup. Connectors are on every plan; the number of connected sites is what varies.
Best practices
Use a dedicated environment or at least a dedicated token
A token created for SearchHandled keeps the audit trail clean and can be revoked independently. If you use environments for staging content model changes, tell us which one is production so entries land in the right place.
Keep field validations as the source of truth
We validate Rich Text and field values against your content model's rules before publishing. Lean into that: express your requirements as Contentful validations and delivered content will conform to them automatically.
Prefer Scheduled Actions over external timing
When a post should go live at a set time, we create a Contentful Scheduled Action rather than holding the publish on our side. The schedule is then visible to your editors and survives anything happening to external systems.
Let editors edit; versioning protects everyone
Because we respect optimistic locking, your editors can touch delivered entries freely. Concurrent changes produce a version conflict we handle by re-fetching, not an overwrite.
Use it in the full SEO workflow
The connector is the last mile, not the strategy. Read the Contentful SEO automation workflow for the evidence gates, draft state, review rules, publish checks, and measurement loop that surround this integration.
Known issues
What practitioners actually report, from official docs, issue trackers, and community forums.
Rate limits with hangs from naive retries
The CMA allows roughly 7 to 10 requests per second and returns 429s at any time; SDK retry behavior has caused pipelines to hang under sustained limiting.
How we handle itWe use bounded backoff that honors the rate limit reset header, with a hard ceiling on retries, so deliveries slow down under limiting instead of hanging.
github.com/contentful
Rich Text is a strict JSON AST
Contentful Rich Text fields accept only a strict JSON document structure, so naive HTML conversion fails validation, often with unhelpful errors about node types.
How we handle itWe convert HTML to the Rich Text AST and validate the result against your field's enabled marks and node types before publish, so validation failures happen in our pipeline where we can fix them, not in yours.
contentful.com, github.com/contentful/contentful-management.rb
409 conflicts from optimistic locking
Publishing or updating with a stale version number returns 409, which happens whenever an editor touched the entry between our read and our write.
How we handle itWe work draft-first, track versions on every operation, and on a 409 we re-fetch the current version and retry, preserving whatever your editors changed.
contentful.com
Questions teams ask
- Will this fight with my editors over entry versions?
No. We follow Contentful's optimistic locking properly: every write carries the version we read, and if an editor changed the entry in between, we get a 409, re-fetch, and retry on top of their changes instead of overwriting them.
- How is scheduling handled?
Through Contentful's own Scheduled Actions. The scheduled publish exists inside Contentful where your editors can see and cancel it, and it fires on time independently of our systems.
- Does my content model need to match a template of yours?
No. We map to your existing content type at setup, whatever its fields are called. The only requirements are a Rich Text or long text field for the body and whatever fields your model marks as required.
Connect Contentful
One tested path from approval to publish.
Bring your content model to setup. We will map the destination and validate a draft before anything goes live.