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.
Connect Contentful to Mattering
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
Test Connection succeeds but the space list is empty
A write is refused with 409 Conflict
An update blanked fields I did not touch
A JSON Patch operation fails on a field that exists in the model
A node reports success but returns no data
An asset was published but its file URL is missing
A bulk action returns immediately and nothing seems to have published
Entries returned by the integration do not match what the website shows
A scheduled action cannot be cancelled
Related
The Contentful MCP
What connecting Contentful unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.