Menu

Mattering Automations Contentful integration

Connect Contentful to Mattering Automations: spaces and environments, content types and editor interfaces, entries with JSON Patch and the full publish lifecycle, assets from URL to CDN, locales, tags, webhooks and their call log, scheduled actions and bulk actions as workflow steps, authenticated with one Content Management API token.

The Mattering Automations Contentful integration adds the Contentful Content Management API to your automation canvas: list spaces and environments, create environments as clones, manage content types and their editor interfaces, work entries through their whole lifecycle (create, create or update, JSON Patch, publish, unpublish, archive, unarchive, delete), build assets from a file URL through processing to the delivery CDN, manage locales and tags, read space webhooks and their recent call log, audit roles and Delivery API keys, queue and cancel scheduled publishing, and run bulk publish, unpublish and validate actions.

The credential is a Content Management API token, created in the Contentful web app by opening the space, clicking Settings, selecting CMA tokens from the drop-down and then Create personal access token, and sent as a bearer token on every request. Delivery and Preview tokens do not work here: they live on the Settings then API keys screen, they are read-only credentials for different hosts and they return 401 against the management API, which matters because they are the tokens most teams already have. The credential also carries a data residency setting, because accounts on EU data residency talk to a different API host, and an optional default space id so a single-space team does not retype the same id on every node. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.

Three Contentful mechanics shape almost every write, and they are worth knowing before the first workflow rather than after it. Writes to an existing resource carry its current sys.version, and a stale version is refused with a 409, so the read comes before the write by design. Entry and asset fields are locale keyed, maps of field id to a map of locale code to value. And the API does not merge: a create or update call replaces the object whole, so anything left out is lost, which is why Contentful: Patch Entry ships as the surgical alternative. Of the 52 nodes, 20 read and 32 act, and seven are flagged destructive: Contentful: Delete Environment, Contentful: Delete Content Type, Contentful: Delete Entry, Contentful: Delete Asset, Contentful: Delete Locale, Contentful: Delete Tag and Contentful: Delete Webhook. The management API documents no trash and no restore for any of them.

Before you start

  • A Contentful account with at least one space, and permission to create a Content Management API token for it. The token inherits your own access, so what the integration can reach is what you can reach.
  • Knowledge of which data residency the account uses. EU data residency is an account level option that Contentful documents as available on higher plans and not included on the Free plan, so most accounts talk to the default API host; accounts that do have it talk to a different one, and a valid token pointed at the wrong host looks exactly like a bad token.
  • The space id and environment id you plan to work in. Both are readable from the integration itself (Contentful: List Spaces and Contentful: List Environments), and environment fields default to master, so a single-environment space needs no extra setup.
  • A Mattering workspace with access to the Automations app.
  • Not required and not stored here: Delivery and Preview API tokens. This integration reads and writes through the management API only, which also serves published content, so no second credential is needed.

Create a Content Management API token

Mattering authenticates to Contentful with a Content Management API token, sent as a bearer token on every request. A personal access token is the quickest route and is created inside the Contentful web app; an OAuth or app token works the same way. The important distinction to get right at this step is which kind of token you are copying, because Contentful issues several and only this one reaches the management API.

Sign in to the Contentful web app, open the space you will work in, and click Settings.
Select CMA tokens from the drop-down, then click Create personal access token. Give it a name that says where it will be used, for example Mattering Automations.
Contentful shows a personal access token once, at creation. Copy it before leaving the page. If it is lost, revoke it and create another rather than hunting for it later.
The tokens on the Settings then API keys screen are Delivery and Preview tokens. Those are read-only credentials for different hosts and they return 401 against the management API, so they will not authenticate this integration. A management token comes from Settings then CMA tokens; if the token you copied came from anywhere else, it is the wrong one.
Note which data residency the account uses. If your Contentful account is on EU data residency, you will select that in the next section, because it changes the API host the integration calls.

Connect Contentful to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Contentful from the list.
Click Create new credential, paste the Content Management API token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Set the data residency on the credential to match the account: the default covers standard accounts, and the EU option switches the integration to the EU data residency host. Optionally set a default space id, which every node falls back to when its own space field is left blank; it never overrides a space id you fill in.
Click Test Connection. Mattering calls Contentful's space list endpoint and reports how many spaces the token can see, so a success also tells you the residency is right. A 401 or 403 names both likely causes, because they produce the same status: the wrong kind of token, or a residency that does not match the account.
Click Connect. All 52 Contentful nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Contentful section should list the query and action nodes. Drop Contentful: List Spaces onto the canvas and run a test step. It is the integration's natural probe: it takes no required parameters, it is the cheapest authenticated read on the API, and the space ids come back at data.items[].sys.id. Copy one, because almost every other node asks for it. Collections all use the same envelope, so paths read data.items[] throughout, while single resource nodes return the bare object at data.sys.id.

Next, run Contentful: List Environments for that space. Every space has master, and any sandbox environments appear beside it; the id you see is the value environment fields take, and those fields default to master. Then run Contentful: List Content Types to see the models entries follow, each with its field schema and display field, and Contentful: List Locales to learn which locale codes are the keys inside every entry and asset fields object. Those four reads give you every id the rest of the integration needs, and all of them are read-only: this verify path cannot reach the seven destructive nodes or change a single value, so it is safe to re-run whenever you rotate the token.

Node reference

52 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 20

Contentful: Get Asset

contentful_get_asset

Fetch one asset with all of its locales, its file details and its current sys.version. A processed asset carries fields.file.<locale>.url; an unprocessed one still carries only the upload URL you gave it.

Contentful: Get Bulk Action

contentful_get_bulk_action

Read the status of a bulk action: created, inProgress, succeeded or failed, with an error object when it failed. Bulk actions run asynchronously, so this is how a workflow waits for one. Records are kept for 7 days.

Contentful: Get Content Type

contentful_get_content_type

Fetch one content type with its complete field list, validations and current sys.version. The read to do before Create or Update Content Type, because that write replaces the field list whole.

Contentful: Get Editor Interface

contentful_get_editor_interface

Fetch a content type's editor interface: which widget renders each field, the sidebar layout, and the current sys.version. The read to do before Contentful: Update Editor Interface, which requires that version.

Contentful: Get Entry

contentful_get_entry

Fetch one entry with all of its locales and its current sys.version. The read to do before any write, since updates replace fields whole and need the version. Empty fields are omitted from the response, so a missing key means no value rather than an error.

Contentful: Get Environment

contentful_get_environment

Fetch one environment, including its creation state. A freshly created environment moves through queued and inProgress before it reaches ready, so poll this node after Create Environment before writing content into it.

Contentful: Get Space

contentful_get_space

Fetch one space with its name, organization and current sys.version. Ask for the space's license metadata by setting include to sys.license.

Contentful: Get Webhook Call Details

contentful_get_webhook_call

Fetch one webhook call in full: the exact request Contentful sent (URL, method, headers, body) and the response it received. The overview tells you a call failed; this tells you why.

Contentful: List Assets

contentful_list_assets

List an environment's assets (images, video, documents), drafts included, with every locale. Each asset's title, description and file live under locale keyed fields, and fields.file.<locale>.url carries the CDN URL once the asset has been processed.

Contentful: List Content Types

contentful_list_content_types

List an environment's content types (the models entries follow), each with its full field schema, display field and current sys.version. This is where entry-shaped automations start: the content type id is what Create Entry needs.

Contentful: List Delivery API Keys

contentful_list_api_keys

List a space's Delivery API keys with the environments each can read and a link to its paired Preview key. accessToken in the response IS the read-only delivery token, so treat this node's output as sensitive.

Contentful: List Entries

contentful_list_entries

List an environment's entries, drafts included, with every locale (this is the management view, not the delivery view). Filter by content type, by full text, or with Contentful's field[operator]=value syntax through the additional query parameters, for example sys.updatedAt[gte] to fetch what changed since a date.

Contentful: List Environments

contentful_list_environments

List a space's environments. Every space has master; sandbox environments are point-in-time copies of it used for QA, staging or CI. The id is the name you use in every other node.

Contentful: List Locales

contentful_list_locales

List an environment's locales. Exactly one has default set to true; that is the locale the Delivery API serves when a request names none. The code is the key inside every entry and asset fields object, so this node is how you learn what those keys are.

Contentful: List Roles

contentful_list_roles

List a space's roles with their permissions and policies, which is what an access audit needs: each policy says which actions are allowed on which content.

Contentful: List Scheduled Actions

contentful_list_scheduled_actions

List the publishes and unpublishes waiting on a schedule, for one environment. Cursor paginated: the response carries a pages object rather than a total. Filter to one entry or asset, or to a status, to see what is queued for it.

Contentful: List Spaces

contentful_list_spaces

List the spaces the management token can access, with their ids, names and organization. Every other Contentful node needs a space id from here. Also the credential health check: a bad or delivery-only token returns 401.

Contentful: List Tags

contentful_list_tags

List an environment's tags, the labels used to group entries and assets. Tags are scoped to one environment. sys.visibility says whether a tag is private (management only) or public (visible through the Delivery API too).

Contentful: List Webhook Calls

contentful_list_webhook_calls

List recent attempts for one webhook, each with the event type, response status code, timings and any errors. This is the first stop when a downstream build stopped triggering: it tells you whether Contentful called at all and what it got back.

Contentful: List Webhooks

contentful_list_webhooks

List a space's webhooks with their target URL, topics, filters and headers. Webhooks are space level rather than environment level: a webhook with no environment filter fires for every environment, and one with no filters property at all fires only for master.

Action nodes 32

Contentful: Archive Entry

contentful_archive_entry

Archive an entry, hiding it from the app's normal content views without deleting it. An entry can only be archived while it is unpublished, so run Contentful: Unpublish Entry first. Reversible with Contentful: Unarchive Entry.

Contentful: Bulk Publish

contentful_bulk_publish

Publish up to 200 entries and assets in one asynchronous action. It returns immediately with a bulk action whose sys.status starts at created: poll Contentful: Get Bulk Action with data.sys.id to learn whether it succeeded. A space can have 5 active bulk actions at once. Reversible with Contentful: Bulk Unpublish.

Contentful: Bulk Unpublish

contentful_bulk_unpublish

Unpublish up to 200 entries and assets in one asynchronous action, returning them all to draft. Poll Contentful: Get Bulk Action with data.sys.id for the outcome. Nothing is deleted. Reversible with Contentful: Bulk Publish.

Contentful: Bulk Validate

contentful_bulk_validate

Check whether a batch of entries and assets would pass validation, WITHOUT publishing anything. Run this before Contentful: Bulk Publish to find the entries that would fail. It changes no content, but it does create a bulk action record, so poll Contentful: Get Bulk Action with data.sys.id for the result.

Contentful: Cancel Scheduled Action

contentful_cancel_scheduled_action

Cancel a pending scheduled action so it never runs. Only actions still in scheduled status can be cancelled; one that already ran cannot be undone from here. Nothing is deleted from the content itself, so this is reversible by scheduling again.

Contentful: Create Entry

contentful_create_entry

Create an entry and let Contentful generate its id. The content type travels in a header, and the field values are locale keyed. The content type must be activated first. New entries are drafts: run Contentful: Publish Entry to make them visible to the Delivery API. Reversible with Contentful: Delete Entry.

Contentful: Create Environment

contentful_create_environment

Create an environment with an id you choose, as a copy of master or of the source environment you name. Cloning is a heavy operation whose duration scales with how much content the source holds, so check Contentful: Get Environment until the state is ready before using it. Reversible with Contentful: Delete Environment.

Contentful: Create Locale

contentful_create_locale

Add a locale to an environment, which adds a new key to every entry and asset fields object. Two locales cannot share a code. Reversible with Contentful: Delete Locale, but note that deleting takes the translated content with it.

Contentful: Create Scheduled Action

contentful_create_scheduled_action

Schedule an entry or asset to publish or unpublish at a future time, which is how an embargo or a timed campaign is built. The time must fall between now and five years ahead. An environment can hold at most 500 scheduled actions in scheduled status, with a separate limit of 200 executing in any single minute. Reversible with Contentful: Cancel Scheduled Action while it is still pending.

Contentful: Create or Update Asset

contentful_create_or_update_asset

Create an asset with an id you choose, or update an existing one. Point the file at a publicly reachable URL and Contentful fetches it during processing. Creating an asset takes three calls: this one, then Contentful: Process Asset, then Contentful: Publish Asset. fields is REPLACED whole, so read the asset first when updating.

Contentful: Create or Update Content Type

contentful_create_or_update_content_type

Create a content type with an id you choose, or update an existing one. IMPORTANT: fields is REPLACED whole, not merged, so read the current type with Contentful: Get Content Type, edit its fields array, and send it all back. A new content type is a draft until Contentful: Publish Content Type activates it.

Contentful: Create or Update Entry

contentful_create_or_update_entry

Create an entry with an id you choose, or update an existing one. IMPORTANT: fields is REPLACED whole. Read the entry with Contentful: Get Entry, change the values you want, and send the entire fields object back, or every value you left out is lost. Send the content type when creating and the version when updating.

Contentful: Create or Update Tag

contentful_create_or_update_tag

Create a tag with an id you choose, or rename an existing one. Name and id must both be unique in the environment. The id and the visibility cannot be changed after creation, so choose both deliberately. Only space admins and users with tag permissions can run this.

Contentful: Create or Update Webhook

contentful_create_or_update_webhook

Create a webhook with an id you choose, or update an existing one. Topics are what fires it, for example Entry.publish. Every list you send replaces its counterpart whole, so read the current definition from Contentful: List Webhooks before editing. Reversible with Contentful: Delete Webhook.

Contentful: Delete Asset

contentful_delete_asset

DESTRUCTIVE: delete an asset and every file it ever referenced on the CDN. There is no restore. Removal from the CDN takes between 24 and 48 hours, and only once the asset is deleted or archived in EVERY environment, so a file that keeps serving is usually a copy still live elsewhere rather than a delete that failed. Capture the asset with Contentful: Get Asset first.

Contentful: Delete Content Type

contentful_delete_content_type

DESTRUCTIVE: delete a content type permanently. It must be deactivated first with Contentful: Unpublish Content Type, and it cannot be deleted while entries still use it. Capture the definition with Contentful: Get Content Type before running this.

Contentful: Delete Entry

contentful_delete_entry

DESTRUCTIVE: delete an entry permanently. The CMA documents no trash and no restore, and other entries linking to this one are left pointing at nothing. Capture it with Contentful: Get Entry first, and prefer Contentful: Archive Entry when you only want it out of the way.

Contentful: Delete Environment

contentful_delete_environment

DESTRUCTIVE: delete a sandbox environment and everything inside it (entries, assets, content types, locales). The master environment cannot be deleted. There is no trash and no restore, so export anything you might want first.

Contentful: Delete Locale

contentful_delete_locale

DESTRUCTIVE: delete a locale AND all content translated into it, across every entry and asset in the environment. Contentful states this cannot be undone, and recreating the same locale does not bring the content back. A locale used as another locale's fallback cannot be deleted.

Contentful: Delete Tag

contentful_delete_tag

DESTRUCTIVE: delete a tag and strip it from every entry and asset that carried it. The grouping is gone and recreating the tag does not reattach it, so anything that filtered on this tag stops matching.

Contentful: Delete Webhook

contentful_delete_webhook

DESTRUCTIVE: delete a webhook definition and its call history. Anything downstream that depended on the notification stops silently. To stop a webhook temporarily instead, set active to false with Contentful: Create or Update Webhook.

Contentful: Patch Entry

contentful_patch_entry

Change individual entry values with JSON Patch, without resending the whole entry. This is the surgical alternative to Create or Update Entry, and the safer one when several automations touch the same entry. The version is REQUIRED. Note that a patch cannot address a field that has never been set: for those, add the whole locale keyed sub-object instead.

Contentful: Process Asset

contentful_process_asset

Process an asset's file for one locale: Contentful fetches the upload URL into its own storage. This is the required middle step between creating an asset and publishing it, and it runs per locale. It returns 204 with no body and may finish after the response, so read the asset back and wait for fields.file.<locale>.url to appear before publishing.

Contentful: Publish Asset

contentful_publish_asset

Publish an asset so it is served by the Delivery API and the asset CDN. Images become available from the image CDN with the Images API resize and crop parameters. The file must have been processed first. Reversible with Contentful: Unpublish Asset.

Contentful: Publish Content Type

contentful_publish_content_type

Activate a content type, which is what makes it usable for entries and visible to the Delivery API. Contentful calls this activating; it is the same PUT on /published that publishes an entry. Validations take effect for entries published after this. Reversible with Contentful: Unpublish Content Type.

Contentful: Publish Entry

contentful_publish_entry

Publish an entry, making it available through the Delivery API. Publishing is a separate call from saving: a draft stays invisible until this runs. Reversible with Contentful: Unpublish Entry.

Contentful: Unarchive Entry

contentful_unarchive_entry

Bring an archived entry back to draft, where editors can see and publish it again. Reversible with Contentful: Archive Entry.

Contentful: Unpublish Asset

contentful_unpublish_asset

Unpublish an asset: it goes back to draft and stops being delivered. Entries that reference its CDN URL will show a missing file until it is published again. Reversible with Contentful: Publish Asset.

Contentful: Unpublish Content Type

contentful_unpublish_content_type

Deactivate a content type: it stops being delivered and no new entries can use it, while the definition itself stays. This is the required step before Contentful: Delete Content Type. Reversible with Contentful: Publish Content Type.

Contentful: Unpublish Entry

contentful_unpublish_entry

Unpublish an entry: it disappears from the Delivery API and returns to draft. Nothing is deleted, the content stays editable. Reversible with Contentful: Publish Entry.

Contentful: Update Editor Interface

contentful_update_editor_interface

Update how a content type is presented to editors: the widget per field, the sidebar, and the entry editor. The version field is REQUIRED here. Each block you send replaces its counterpart whole, so read the current interface first with Contentful: Get Editor Interface.

Contentful: Update Locale

contentful_update_locale

Update a locale. The version field is REQUIRED. Changing the code changes the keys in every future API response and will break clients that expect the old one, and it is refused outright while another locale uses this one as its fallback. The default flag cannot be changed.

Using the integration

On the automation canvas

Contentful nodes chain with every other node: an approved task in Mattering Productivity can trigger Contentful: Create Entry and then Contentful: Publish Entry, a scheduled sweep can pull recently changed content with Contentful: List Entries into a Mattering database, and a failed delivery can be diagnosed with Contentful: List Webhook Calls without leaving the canvas. Four ids do most of the work and all four come from listers: the space id from Contentful: List Spaces, the environment id from Contentful: List Environments, the content type id from Contentful: List Content Types, and locale codes from Contentful: List Locales. Space, environment, content type, locale, tag, webhook and scheduled action fields offer dropdown pickers built from those listers.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive the same surface. A useful agent loop is read, patch, publish: Contentful: Get Entry returns the entry with its version, Contentful: Patch Entry changes only the values named, and Contentful: Publish Entry makes the result live. The read nodes are the safest surface to hand an agent, and the seven destructive nodes belong behind conditions or approval steps rather than in an agent's open toolset. Contentful ships its own MCP server as well, hosted at https://mcp.contentful.com/mcp and available locally as an open source server run with npx @contentful/mcp-server, covering content types, entries, assets, spaces, environments, locales, tags and AI Actions. The difference is where the tools run: if all you need is an assistant talking to one Contentful space, that is the shorter path and worth using, while these nodes are steps in a workflow canvas alongside every other connector, able to fire on a schedule or a trigger rather than only inside a chat.

The version header, and what a 409 is telling you

Contentful uses optimistic locking: a write to an existing resource carries that resource's current sys.version, and if anything changed since you read it, the write is refused with a 409 instead of overwriting the other edit. The version is required on the pure update nodes (Contentful: Patch Entry, Contentful: Update Locale, Contentful: Update Editor Interface) and optional on the create or update nodes, because the same endpoint also creates resources that have no version yet: leave it blank when creating, fill it when updating. On publish, unpublish, archive, unarchive and delete it is optional, and sending it is still the habit that stops a workflow from publishing a draft that changed after it was read. Wherever a version is needed, the step before it is the matching read, and the value is at data.sys.version.

Whole-object replacement, and the patch node that avoids it

The management API does not merge. Contentful: Create or Update Entry sends the entire fields object, so any field left out of the request is lost, and the same applies to Contentful: Create or Update Content Type, Contentful: Create or Update Asset and Contentful: Create or Update Webhook, where each list you send replaces its counterpart whole. The documented order is read, modify, write back with the version. Contentful: Patch Entry is the alternative and the better default when several automations touch the same entry, because it sends JSON Patch operations that touch only what they name. One documented limit: a patch cannot address a field that has never been set on the entry, so a first value has to be added as the whole locale keyed sub-object.

Locale keyed fields

Entry and asset field values are maps of field id to a map of locale code to value, so a title is not a string but a small object keyed by the codes Contentful: List Locales reports. Exactly one locale is the default, and empty fields are omitted from responses entirely, so a missing key means no value rather than an error, and a template that assumes a key exists is the usual cause of a blank downstream step. On the publish side, Contentful: Publish Entry and Contentful: Publish Asset both carry an optional field for publishing specific locales instead of the whole record; Contentful documents locale based publishing as available only on specific pricing plans and points you at your Contentful sales contact to confirm which ones, so leave it blank unless you know your plan includes it.

Assets take three calls, not one

Contentful: Create or Update Asset points the file at a publicly reachable URL, Contentful: Process Asset makes Contentful fetch it into its own storage for one locale, and Contentful: Publish Asset puts it on the delivery CDN. Processing answers with no body, and that response is not a promise the file is ready, so the reliable pattern is to read the asset back with Contentful: Get Asset and wait for the processed file URL to appear before publishing. This three-step shape is also why the integration needs no binary upload node: the automation already has a URL for the file, which is the path Contentful's own asset creation supports.

Bulk and scheduled actions are asynchronous

Contentful: Bulk Publish, Contentful: Bulk Unpublish and Contentful: Bulk Validate all return immediately with a bulk action record rather than a result, so the workflow reads data.sys.id and polls Contentful: Get Bulk Action until the status settles on succeeded or failed. Contentful documents a limit of 5 active bulk actions per space, 200 items per action, and record retention of 7 days. Running Contentful: Bulk Validate before Contentful: Bulk Publish turns a risky release into a report, because it finds the entries that would fail without publishing anything. Scheduled publishing works the same way from the other end: Contentful: Create Scheduled Action queues a publish or unpublish for a future time, Contentful: List Scheduled Actions shows what is pending, and Contentful: Cancel Scheduled Action removes one that has not run yet. Contentful documents a limit of 500 scheduled actions in scheduled status per environment, with a separate limit of 200 scheduled actions executing in any single minute, and the scheduled time has to fall between now and up to five years ahead.

The seven destructive nodes, gated

Contentful: Delete Locale is the heaviest in blast radius: it removes the locale and every translation into it across the whole environment, and recreating the locale does not bring the content back; Contentful refuses the delete outright in two cases, because a space's default locale cannot be deleted and neither can a locale that another locale uses as its fallback. Contentful: Delete Environment takes everything inside the environment with it, though master cannot be deleted. Contentful: Delete Asset removes the files the asset referenced, and Contentful documents that removal from the CDN takes between 24 and 48 hours, and only once the asset has been deleted or archived in every environment, so a file that keeps serving is usually a copy still live in another environment rather than a delete that failed. Contentful: Delete Entry leaves other entries linking to nothing, and Contentful: Delete Content Type requires deactivating the type first, with a refusal to be expected while entries still use the type. Contentful: Delete Tag strips the tag from everything that carried it, and Contentful: Delete Webhook silently ends whatever depended on the notification. The pattern for all seven is the same: read the object first so the run holds a copy, prefer Contentful: Archive Entry when you only want content out of the way, prefer setting a webhook inactive over deleting it, and put deletes behind a condition, an approval task, or a manual run rather than a bare trigger.

What stays off the canvas

Four boundaries are deliberate. The Content Delivery API is not here: it takes a different token on a different host and returns a different shape (links resolved, locales collapsed), and two entry shapes under similar node names would break every path expression written against them, while the management API already reads published content with the same token this integration holds. Raw binary uploads are not here either, because a canvas cannot author an octet-stream body and Contentful: Create or Update Asset already takes a public file URL. Releases are omitted on this build's own reading of the create-a-release payload: it takes more than one shape, and one node form cannot be right for all of them; bulk actions cover the batch publishing need meanwhile. And the administration surfaces (organizations, teams, memberships, app definitions, snapshots, usage) sit outside the automation core, along with space creation and deletion, which Contentful documents as unrecoverable.

Troubleshooting

Test Connection fails with a 401 or 403
Two different mistakes produce the same status, and the failure message names both. The first is the wrong kind of token: Delivery and Preview tokens authenticate read-only hosts and never work against the management API, so confirm the token came from Settings then CMA tokens, and not from the Settings then API keys screen where the Delivery and Preview keys live. The second is data residency: an account on EU data residency answers on a different host, and a perfectly valid token pointed at the default host gets rejected. Open the credential in Connectors, set the residency to match the account, and click Test Connection again. Also check for whitespace picked up in the copy, and confirm the token has not been revoked in Contentful since you saved it.
Test Connection succeeds but the space list is empty
A management token can only see what your own Contentful user can see, so an empty list usually means the token belongs to a user with no space access, or that you created it in a different organization than the one holding the spaces you want. Check your access in the Contentful web app first, then create the token again under Settings then CMA tokens from the account that has it. This is also worth ruling out before assuming a residency problem: residency mismatches normally fail outright with a 401 rather than returning an empty but successful list, and Contentful: List Spaces is the node to re-run once the access is fixed.
A write is refused with 409 Conflict
That is optimistic locking doing its job: the version sent with the write is not the resource's current version, which means the resource changed after it was read. Put the matching read immediately before the write in the same run, take data.sys.version from it, and pass that value to the write rather than a version captured earlier or hard-coded. If two automations write to the same entry, expect this occasionally by design; handle it by re-reading and retrying rather than by removing the version, since removing it on the nodes where the API requires it just changes the error. Contentful: Patch Entry reduces how often the conflict matters, because it touches only the values it names.
An update blanked fields I did not touch
This is whole-object replacement rather than a bug. Contentful: Create or Update Entry sends the entire fields object, so any field missing from the request is removed, and the same is true of Contentful: Create or Update Content Type, Contentful: Create or Update Asset and Contentful: Create or Update Webhook, where each list replaces its counterpart. The safe pattern is read, modify, write back: run Contentful: Get Entry, edit the returned fields object, and send all of it with the version. When only a value or two changes, use Contentful: Patch Entry instead, which is built precisely so a partial update cannot cost you the rest of the record.
A JSON Patch operation fails on a field that exists in the model
A patch cannot address a field that has never been set on that particular entry, even when the content type defines it. Entries omit empty fields entirely, so the path the patch names does not exist in the stored object yet. Add the whole locale keyed sub-object for that field first with Contentful: Create or Update Entry (the field id mapped to a locale code and a value), then subsequent patches can address it normally. Contentful: Get Entry shows what is actually stored, which is the quickest way to tell a genuinely missing field from a typo in the path.
A node reports success but returns no data
Several Contentful endpoints answer with no body, and the nodes pass that through honestly rather than inventing a payload. The deletes and Contentful: Process Asset are the common ones. Success is the status itself, so a workflow that needs to confirm the outcome should follow with a read: Contentful: Get Asset after processing, or the matching lister after a delete. A downstream step that reads a path out of an empty data object is the usual reason a run continues but produces nothing.
An asset was published but its file URL is missing
The file was probably never processed, or processing had not finished when the publish ran. Creating an asset takes three calls: Contentful: Create or Update Asset with a publicly reachable file URL, then Contentful: Process Asset for the locale, then Contentful: Publish Asset. Processing returns no body, and that response is not a promise the file is ready, so put a read of Contentful: Get Asset between processing and publishing and wait for the processed file URL to appear. The other cause is a source URL Contentful could not fetch: the URL has to be publicly reachable from Contentful's own infrastructure, not just from your network.
A bulk action returns immediately and nothing seems to have published
Bulk actions are asynchronous. Contentful: Bulk Publish, Contentful: Bulk Unpublish and Contentful: Bulk Validate all return a bulk action record whose status starts at created, not a finished result, so the run looks instant because the work has only been queued. Read data.sys.id from that response and poll Contentful: Get Bulk Action until the status is succeeded or failed, where a failure carries an error object naming what went wrong. Contentful documents a maximum of 200 items per action and 5 active actions per space, so a large batch needs splitting and a busy space may need the workflow to wait before starting another.
Entries returned by the integration do not match what the website shows
They are two different views on purpose. This integration reads through the management API, which returns drafts alongside published content, every locale rather than one, and unresolved links, while a website usually reads the Delivery API, which serves published content only with links resolved. So an entry appearing in Contentful: List Entries is not evidence that it is live. Check the entry's publish state in its sys block, and remember that saving and publishing are separate calls: a draft stays invisible to the Delivery API until Contentful: Publish Entry runs.
A scheduled action cannot be cancelled
Only actions still in the scheduled status can be cancelled; once one has run, it is a completed publish or unpublish and cancelling is no longer meaningful. Run Contentful: List Scheduled Actions filtered to the pending status to see what is genuinely cancellable, and undo an action that already ran with its opposite, Contentful: Unpublish Entry after an unwanted publish, for example. Creation has its own rule worth knowing here: Contentful documents the scheduled time as having to fall between now and up to five years ahead, so a workflow computing a timestamp that has already passed by the time the run reaches the node fails at creation rather than later.

Contentful is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products