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.
Connect DeepL to Mattering
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
A DeepL Write node returns a permission error while the translation nodes work
Nodes start failing with HTTP 456
DeepL: Download Translated Document returns 503
The document_id returns 404 on a second download
A translation with a glossary_id fails or the glossary is ignored
DeepL: Upload Document fails before anything reaches DeepL
DeepL: Edit Glossary rejects a config that fills only some dictionary fields
Requests fail with 429 during a burst
Related
The DeepL MCP
What connecting DeepL 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.
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.