Menu

Mattering Automations DeepL integration

Connect DeepL to Mattering Automations: text translation with glossaries, formality, and context, HTML and XML tag handling, DeepL Write rephrasing and grammar correction, asynchronous document translation, and v3 multilingual glossaries as workflow steps, authenticated with one API key.

The Mattering Automations DeepL integration adds DeepL's translation API to your automation canvas: translate text with context, formality, model selection, and glossary support, translate HTML and XML with the markup kept intact, rephrase and correct text with DeepL Write, run asynchronous document translation for docx, pptx, xlsx, pdf, html, txt, xliff, srt, and more, manage v3 multilingual glossaries, and read the language rosters and account usage that the rest builds on.

The credential is a single API key from your DeepL account, sent on every request in DeepL's own header scheme, Authorization: DeepL-Auth-Key, rather than a Bearer token; the integration formats the header for you. One detail the integration absorbs entirely: DeepL runs two servers for the same API, api-free.deepl.com for Free keys, which always end in :fx, and api.deepl.com for Pro keys, and the connector reads the key and routes each request to the right server automatically, so one credential type serves both plans and there is no host to configure. Setup takes a few minutes once the key exists, and this guide walks through each step and ends with the full node reference.

The safety modeling is stated on the nodes rather than buried. Of the 18 nodes, ten read and eight act, and exactly one carries a destructive flag: DeepL: Delete Glossary, which is permanent and breaks translations referencing the deleted id. Two more honesty notes travel with the nodes: every translation, Write, and document call bills characters against the account quota, so those calls are spend rather than free reads, and DeepL: Download Translated Document is single use, because DeepL deletes the finished document from its servers after one successful download. DeepL's admin-only analytics API is deliberately not shipped.

Before you start

  • A DeepL API plan. DeepL API Free covers every node here except the two DeepL Write nodes; sign up at deepl.com/pro-api. DeepL's API plans are separate from its translator app subscriptions, so an API key comes from an API Free or API Pro plan specifically.
  • For the DeepL Write nodes, DeepL: Rephrase Text and DeepL: Correct Text, a DeepL API Pro subscription: DeepL documents Write as not yet available on API Free plans, so Free keys, the ones ending in :fx, get a permission error on those two nodes.
  • A Mattering workspace with access to the Automations app.
  • For document translation, a plan for where the result goes: the download is single use and returns the file as base64 inside the run, so decide the downstream step, a database write, a task attachment, a storage node, before running it.

Get your DeepL API key

Mattering authenticates to DeepL with an API key sent on every request as Authorization: DeepL-Auth-Key, DeepL's own scheme rather than a Bearer token; the connector formats the header for you. The same credential serves both plans: Free keys always end in :fx and belong to api-free.deepl.com, Pro keys belong to api.deepl.com, and the connector reads the key's suffix and picks the correct server per request.

Sign in at deepl.com and open your account's API keys page at deepl.com/your-account/keys.
Copy an existing key, or create a new key named for the automation so it can be rotated or deactivated independently of anything else using the account.
A key ending in :fx is a Free key. You never need to know or configure which DeepL server a key belongs to: the connector detects the :fx suffix and routes to api-free.deepl.com, and routes every other key to api.deepl.com.
On an API Free plan every node in this integration works except the DeepL Write nodes, Rephrase Text and Correct Text: DeepL documents Write as not yet available on API Free plans and requiring an API Pro subscription. A permission error on those nodes with a :fx key is the plan speaking, not a broken credential.

Connect DeepL to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose DeepL from the list.
Click Create new credential, paste the API key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering calls DeepL's usage endpoint on the server your key belongs to: success returns the current billing period's character counters and proves the credential, an error means the key is mistyped or deactivated.
Click Connect. All 18 DeepL nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a DeepL section should list the query and action nodes. Drop DeepL: Get Usage onto the canvas and run a test step. It is the integration's universal probe: it works with every valid key on either plan, takes no parameters, and returns the current billing period's character_count and character_limit without echoing the key. Pro keys additionally report per-key and per-product counters. If this node succeeds the credential is healthy; anything failing after it is a parameters, plan, or quota question, not an authentication one.

Next, run DeepL: List Source Languages and DeepL: List Target Languages. They return the language rosters and are the same calls that populate the language pickers on the translate and document nodes, so seeing them succeed means the pickers will fill. If you plan to use glossaries, run DeepL: List Glossaries too and note the glossary_id values it returns, because the translate, document, and glossary nodes all take them. Everything in this verify path is read-only and bills nothing, the language listers and usage gauge are Safe Reads, so it is safe to re-run whenever you rotate the key.

Node reference

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

Read and query nodes 10

DeepL: Download Translated Document

deepl_download_document

Download the translated document as base64 (data.file_base64, up to about 5 MB). SINGLE-USE: DeepL deletes the document from its servers after one successful download and the document_id 404s afterwards - store the result downstream in the same run. Wait for status done first; downloading earlier returns 503. Re-uploading the source document repeats the process if the result is lost.

DeepL: Get Document Status

deepl_get_document_status

Poll a document translation: status is queued, translating (with seconds_remaining), done (with billed_characters), or error (with a message). A pure status read - the POST method only carries the document_key.

DeepL: Get Glossary

deepl_get_glossary

Fetch one glossary's metadata: name, its dictionaries (language pairs with entry counts), and creation time. Entries themselves come from DeepL: Get Glossary Entries.

DeepL: Get Glossary Entries

deepl_get_glossary_entries

Read one dictionary's entries from a glossary as tab-separated text (data.dictionaries[0].entries). The natural backup step before Edit or Delete Glossary.

DeepL: Get Usage

deepl_get_usage

Read the account's usage for the CURRENT billing period: characters translated so far and the character limit (near-real-time). Pro keys additionally report per-key counters, per-product breakdowns, and the period's start and end times. Works with every valid key, so this is the credential health check to run first in any DeepL automation. A snapshot gauge, not a windowed report.

DeepL: List Glossaries

deepl_list_glossaries

List the account's glossaries with their IDs, names, and per-language-pair dictionaries (entry counts included). The glossary_id from here feeds the translate, document, and glossary nodes.

DeepL: List Glossary Language Pairs

deepl_list_glossary_language_pairs

List the source/target language pairs glossaries support. Feeds the glossary nodes' language pickers. (DeepL marks this v2 path deprecated in favor of /v3/languages?resource=glossary, but only this one returns explicit PAIRS.)

DeepL: List Languages by Resource

deepl_list_languages

The current (v3) language roster for a specific DeepL capability: translate_text, translate_document, glossary, write, and others. Each row carries usable_as_source / usable_as_target flags, stability status, and per-feature support (formality, tag handling, glossary). Returns a bare array (data[].lang / data[].name).

DeepL: List Source Languages

deepl_list_source_languages

List the languages DeepL can translate FROM, as code plus English name. Returns a bare array, so rows sit at data[].language / data[].name. Feeds the source_lang pickers across the translate and document nodes.

DeepL: List Target Languages

deepl_list_target_languages

List the languages DeepL can translate INTO, each with whether it supports the formality option. Returns a bare array (data[].language / data[].name / data[].supports_formality). Feeds the target_lang pickers.

Action nodes 8

DeepL: Correct Text

deepl_correct_text

Fix spelling and grammar with DeepL Write, changing as little as possible - no rephrasing, no style changes (use DeepL: Rephrase Text for those). DeepL docs state Write is not yet available on API Free plans and requires a DeepL API Pro subscription, so free (:fx) keys get a permission error here. Bills characters against the account quota.

DeepL: Create Glossary

deepl_create_glossary

Create a glossary with one dictionary (a source/target language pair plus its entries). DeepL v3 glossaries are multilingual: add further language pairs later with DeepL: Edit Glossary, or via Extra body fields. Reversible with DeepL: Delete Glossary. Glossaries cap at 10 MiB.

DeepL: Delete Glossary

deepl_delete_glossary

DESTRUCTIVE: delete a glossary and every dictionary in it, permanently. Translations referencing its glossary_id start failing. Export the entries first with DeepL: Get Glossary Entries if there is any doubt.

DeepL: Edit Glossary

deepl_edit_glossary

Rename a glossary and/or REPLACE one dictionary: providing source_lang, target_lang, and entries overwrites that language pair's entire entry set (or adds the pair if new). Fill only the name to rename without touching entries. Fetch the current entries first with DeepL: Get Glossary Entries if you need to merge rather than replace.

DeepL: Rephrase Text

deepl_rephrase_text

Improve text WITHIN its own language with DeepL Write: rephrase for clarity, apply a writing style, or adjust the tone. Bills characters against the account quota. DeepL's docs state Write is not yet available on API Free plans and requires a DeepL API Pro subscription, so free (:fx) keys get a permission error here. Request body up to 10 KiB.

DeepL: Translate Tagged Text

deepl_translate_tagged_text

Translate HTML or XML content while keeping the markup intact: same /v2/translate endpoint as DeepL: Translate Text, with the tag-handling controls exposed. Bills characters against the account quota. The classic use is translating CMS page fragments or product HTML without breaking the tags.

DeepL: Translate Text

deepl_translate_text

Translate text into a target language, with optional context, formality, glossary, and model selection. A stateless call that creates nothing server-side but bills characters against the account quota. Plain UTF-8 text up to 128 KiB per request; for HTML or XML content use DeepL: Translate Tagged Text instead.

DeepL: Upload Document

deepl_upload_document

Upload a document for translation: the runner downloads the file from the URL you provide and sends the bytes to DeepL. Supported formats include docx, pptx, xlsx, pdf, html, txt, xliff, srt, and more. Asynchronous: the response returns a document_id and document_key - poll DeepL: Get Document Status, then fetch DeepL: Download Translated Document. Bills the document's characters against the account quota once translation starts.

Using the integration

On the automation canvas

DeepL nodes chain with every other node: a CMS webhook can run DeepL: Translate Tagged Text on a published page and open a review task in Mattering Productivity, a support workflow can translate an inbound message with DeepL: Translate Text and route it, and translated content can land in a Mattering database keyed by path and language. The values almost every downstream node asks for come from the listers: language codes from DeepL: List Source Languages and DeepL: List Target Languages, and glossary ids from DeepL: List Glossaries.

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. An agent can check headroom with DeepL: Get Usage, pick the right glossary with DeepL: List Glossaries, translate with DeepL: Translate Text, and file the result. The read nodes are the safest surface to hand an agent; remember that translation calls bill characters, and keep DeepL: Delete Glossary, the one destructive node, behind a condition or an approval step.

HTML and XML without broken markup

DeepL: Translate Tagged Text translates HTML or XML while keeping the tags intact: set tag_handling to html or xml and the markup survives the round trip, which is the move for CMS fragments, product descriptions, and email templates. XML gets finer controls: splitting_tags and non_splitting_tags steer where sentences split, outline_detection can be turned off to control structure entirely by tag lists, and ignore_tags leaves content such as code untranslated. It is the same DeepL endpoint as DeepL: Translate Text, shipped as its own node so plain-text configs never carry the tag options.

Document translation, start to finish

DeepL: Upload Document takes a file URL, downloads it (up to 20 MB), and submits the bytes to DeepL; the filename needs an extension, provided in the config when the URL path lacks one, because DeepL detects the document type from it. The upload returns a document_id and a document_key, and both must be piped downstream since DeepL cannot decrypt the document without the key. Poll DeepL: Get Document Status until it reports done, then fetch DeepL: Download Translated Document exactly once: the download is single use, DeepL deletes the document server-side after one successful fetch and the id 404s afterwards, so store the base64 result, up to about 5 MB, in the same run. Downloading before the status is done returns 503, which is a timing signal rather than an outage.

Glossaries with a backup habit

The glossary nodes build on DeepL's v3 multilingual glossaries, the surface DeepL's docs recommend over the older v2 endpoints: one glossary holds one or more dictionaries, each a source and target language pair with its own entries. DeepL: Create Glossary starts with one dictionary from tab-separated or CSV term pairs, and DeepL: Edit Glossary renames, adds a pair, or replaces an existing pair's entries entirely, so run DeepL: Get Glossary Entries first when you mean to merge rather than replace. The same export is the right step before DeepL: Delete Glossary, which is permanent and flagged destructive. One rule the translate nodes state: applying a glossary_id requires source_lang to be set on the request.

Spend awareness built into workflows

Every translation, Write, and document call bills characters against the account quota, and the node descriptions say so instead of presenting translation as a free read. DeepL: Get Usage is the gauge: characters used this billing period against the limit, cheap enough to run at the top of any heavy workflow so it can stop early rather than fail mid-run. Two useful details: the context field on DeepL: Translate Text shapes the translation without being billed, and show_billed_characters returns the billed count per translation. Batching helps too: text translation accepts up to 50 texts in one call.

Troubleshooting

Test Connection fails with an authorization error
The test calls DeepL's usage endpoint, which works with every valid key on either plan, so a failure here is about the key itself. Check for leading or trailing whitespace from the copy, and confirm the key was not deactivated or regenerated on the API keys page at deepl.com/your-account/keys. If the account only has a DeepL translator app subscription, that is the gap: API keys come from DeepL's API Free and API Pro plans specifically, so sign up at deepl.com/pro-api and use a key from that plan.
A DeepL Write node returns a permission error while the translation nodes work
That is DeepL's documented plan restriction, not a fault: DeepL states Write is not yet available on API Free plans and requires an API Pro subscription, so keys ending in :fx are refused on DeepL: Rephrase Text and DeepL: Correct Text. The translation, document, glossary, and language nodes carry no such restriction and work on the same key. To use Write, connect a credential from an API Pro subscription.
Nodes start failing with HTTP 456
456 is DeepL's own status code for quota exceeded: the account has used its character allowance for the billing period, and translation, Write, and document calls will keep failing until there is headroom. Run DeepL: Get Usage to see character_count against character_limit, then either wait for the period to reset or move the account to a plan with a higher limit. Workflows that translate at volume should run the usage node first and stop early instead of discovering the wall mid-run.
DeepL: Download Translated Document returns 503
The translation is not finished yet: DeepL returns 503 for a download requested before the document reaches status done. Poll DeepL: Get Document Status in a loop with a wait step; while translating it reports seconds_remaining, and when it reports done the download succeeds. This is sequencing rather than an outage, and the fix is always to gate the download on the status node.
The document_id returns 404 on a second download
That is DeepL working as designed: the download is single use, and DeepL deletes the document from its servers after one successful fetch, so the id 404s from then on. Build the workflow to store the base64 result downstream in the same run, into a database, a file store, or a task attachment, the moment the download node returns. If the result was lost, re-upload the source document with DeepL: Upload Document and run the status and download steps again; the characters are billed again when translation restarts.
A translation with a glossary_id fails or the glossary is ignored
Two requirements stack here. First, using a glossary requires source_lang to be set on the request: auto-detect and glossaries do not combine, and the nodes state this on the glossary field. Second, the request's source and target languages must match one of the glossary's dictionaries; a v3 glossary holds specific language pairs, and DeepL: Get Glossary shows exactly which pairs a glossary contains. Check both, and confirm the pair itself is supported with DeepL: List Glossary Language Pairs.
DeepL: Upload Document fails before anything reaches DeepL
The node takes a file URL and the runner downloads it before submitting, so the URL must be publicly reachable, a signed storage URL from an upstream node is the usual shape, and the file must be 20 MB or smaller. DeepL also detects the document type from the filename's extension, so when the URL path has no extension, fill the filename field with one, for example report.docx. If the download side is fine but DeepL rejects the file, check the format against the supported list: docx, pptx, xlsx, pdf, html, txt, xliff, srt, and more.
DeepL: Edit Glossary rejects a config that fills only some dictionary fields
The dictionary fields travel together: source_lang, target_lang, and entries must all be provided to replace or add a language pair, and the node enforces all-three-or-none so a half-built pair never goes on the wire. Filling only the name is valid and renames the glossary without touching entries. Remember that providing the three dictionary fields replaces that pair's entire entry set, so export the current entries with DeepL: Get Glossary Entries first when the intent is to merge.
Requests fail with 429 during a burst
DeepL returns 429 when requests arrive too quickly and expects the client to wait and resend. The nodes report the 429 on their output rather than silently retrying, so add a wait step between calls in a loop and spread scheduled sweeps apart. Batching removes requests entirely, which beats delaying them: DeepL: Translate Text accepts up to 50 texts in a single call as a JSON array, so one batched call replaces dozens of single-text requests.

DeepL 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