OpenAI

GPT models, called directly at OpenAI.

Connect an OpenAI API key so that AI nodes can work with GPT models. The connection is set up once for the whole organisation by an administrator; members then use it from the workflow editor without ever seeing the key.

Requests go directly to OpenAI’s API. The address is fixed and cannot be replaced by another server: to call a different OpenAI-compatible server, use the OpenAI-compatible API connection instead.

At a glance

• Identifier: openai
• Family: AI provider
• Set up by: An administrator, for the whole organisation
• Authentication: Provider API key
• Credential type: llm_provider

Before you start

• An OpenAI Platform account with billing set up, so that the key can make calls.
• An administrator account on Mankomail: only administrators manage AI connections.
• An instance with an encryption key (ENCRYPTION_KEY), required to store any secret.

Who configures it

AI connections belong to the organisation, not to a member. Only an administrator can create, edit, test or delete them, from the Connections page. Members see the Artificial intelligence section with the note “AI providers are configured once for the whole organisation, by an administrator.” They never see a key: in the workflow editor they only pick a connection by its label and a model.

The key is encrypted before it is stored and is never displayed again: the screen only shows its last four characters (“Key saved (ends with …)”). Storing a key requires the instance encryption key (ENCRYPTION_KEY, see Environment variables); without it, saving fails with llm.encryption_disabled.

Create an API key at OpenAI

1. Sign in to the OpenAI Platform and open the API keys page: https://platform.openai.com/api-keys. In Mankomail, the Where do I get this key? link of the OpenAI card opens this page.
2. Create a new secret key. Name it after your instance so you can recognise it later.
3. Copy the key right away and keep it until you paste it in Mankomail: it is not shown in full again.

Add the connection

1. Open Connections in the main navigation.
2. In the Artificial intelligence section, find the OpenAI row and click Configure. (You can also click Add in that section and pick OpenAI in the catalogue.)
3. Label: pre-filled with the provider name. Change it if you plan to hold several keys (“Prod”, “Client X”).
4. API key: paste the key. It is required for a new connection and is never shown again.
5. (No server URL to enter: requests always go to the provider’s official address, which cannot be changed.)
6. Enabled models: see the section on enabled models below.
7. Click Save, then Test.

Test is only available once the connection is saved. When you edit a saved connection, leave the API key field empty to keep the stored key; paste a new key only to replace it.

Choose the enabled models

OpenAI has a built-in catalogue in Mankomail:

Model	Input	Output	Note
gpt-5-nano	$0.05	$0.40	Recommended for classify, extract and mailbox analysis
gpt-5-mini	price not listed	price not listed	Recommended for compose and general use
gpt-5	price not listed	price not listed

Prices are per million tokens. “price not listed” means Mankomail does not know the price: those calls are counted without a cost.

• With every model ticked (the initial state), there is no restriction: nodes may also name an OpenAI model that is not in this list.
• Untick models to restrict the connection: a node that names an unticked model then fails with llm.model_not_allowed. You must keep at least one model.

These GPT-5 models reason before answering. Mankomail accounts for it: for structured answers it requests a low reasoning effort and adds a margin of output tokens for the reasoning. The temperature parameter is not sent to them.

Test the connection

Test sends a real, minimal request (“ping”, at most 5 output tokens) with the key of the connection shown in the card. It proves the key can complete, not just that it is accepted. The test uses gpt-5-nano when it is enabled, otherwise the first enabled model. On success the card shows “Connected to model in n ms.”; otherwise “The test failed:” followed by the reason (see Common errors).

Which provider and model an AI node uses

AI nodes (such as Categorize, Extract, Compose (AI), Summarize and Free instruction (AI)) each call the model with a purpose: classify, extract, compose or general use. Mailbox analysis uses its own purpose. For every call, the provider and model are resolved in this order — the first rule that applies wins:

1. A provider node linked to the node’s model port — for example the OpenAI (GPT) node. Its Connection and Model fields apply; an empty Model means “the recommended model for this purpose at this provider”.
2. The administrator’s choice for that purpose, in the Which AI for which use panel of the Connections page.
3. The instance default — the first row of that panel, “Default (every unset use)”. It can name a provider only (“… · recommended model”) or a provider and a model.
4. The first configured provider, by configuration date (no brand preference), with the recommended model for the purpose.

A choice that has become unusable (key removed, model unticked) is skipped in favour of the next rule, and the panel shows “Choice not applicable” next to it. Under each row, “Uses: provider · model” shows what the next call will really get. When nothing can serve a purpose, the row shows “None” and the nodes fail with llm.no_provider_configured or llm.no_default_model.

When OpenAI is the provider and no model is named, the recommended models are gpt-5-nano for classify, extract and mailbox analysis, and gpt-5-mini for compose and general use. The badges “Default: …” on the OpenAI card show which purposes OpenAI currently serves.

Several keys for the same provider

An organisation can hold several OpenAI connections — for example a production key and a key billed back to one client. Each connection has its own Label, key and list of enabled models.

• To add one, open the provider card and click Add a connection. The label is required and must be unique (“Another connection already uses this label.” otherwise).
• The provider’s first connection automatically becomes its Default connection. Once there are two or more, the card lists them; click Make default on another one to move the default.
• The default connection is what everything uses when no connection is named: per-use defaults, the instance default, mailbox analysis, and any provider node whose Connection field is left on “Default (…)”.
• To pick a specific key for one node, choose it in the Connection field of the OpenAI (GPT) provider node.

To delete a connection, select it, click Delete, then Confirm deletion. Two refusals protect running workflows:

• if published workflows reference the connection, the card says “Published workflows use this connection; confirm to delete it anyway.” and lists them. Confirming again deletes it, and those nodes will then fail with llm.connection_not_found until you pick another connection;
• the default connection cannot be deleted while the provider has other connections (llm.connection_is_default): make another one the default first. Deleting the last connection removes the provider from the instance.

Use OpenAI in a workflow

To make one AI node work with OpenAI whatever the instance defaults are, link a provider node to it:

1. Add the OpenAI (GPT) node to the canvas (node reference).
2. Draw a link from it to the model port of the AI node.
3. In Connection, keep “Default (…)” to use the provider’s default connection, or pick another connection by its label.
4. In Model, leave the field empty to use the recommended model for the node’s purpose, or enter a model id. The editor suggests the models enabled on the chosen connection and warns when the id is not enabled on it (“This model is not enabled on the selected connection: the run will refuse it.”).
5. Temperature is optional; leave it empty to keep the provider’s setting.

The provider node is not a step: it never runs on its own, carries no key, and only tells the linked AI node which provider, connection and model to use. One provider node can feed several AI nodes.

If the chosen connection has been deleted, the run fails with llm.connection_not_found — it never falls back to another key. If the connection belongs to another provider, the run fails with llm.connection_provider_mismatch.

Structured output

When a node expects a structured answer, Mankomail sends the expected JSON schema to OpenAI as a non-strict json_schema response format, so schemas written in the editor do not need OpenAI’s strict-mode constraints. If the answer still cannot be read, Mankomail makes one repair attempt; after that the step fails with llm.invalid_json. A structured answer cut off by the output ceiling fails with llm.output_truncated, and a reasoning model that wrote nothing fails with llm.empty_output.

In a test run

A test run calls the real model: you see the category, extraction or draft the model actually produces. Only irreversible actions (sending, moving, HTTP requests) are simulated. A test call costs the same as in production and appears in AI usage and costs.

The output is fabricated only when the instance has no usable provider — no AI connection at all, or a provider node linked to a provider that is not configured. The editor then shows “AI skipped: no key on this instance”, and the step’s effect says that no model would have been called because no LLM provider is configured. When a model can be resolved, the effect names the model the run would really use. The fabricated output is the smallest value that fits the expected shape: the first category set to true, text fields set to simulated.

Policy refusals are not hidden in a test run: a model that is not enabled (llm.model_not_allowed), a deleted connection (llm.connection_not_found), an exhausted quota or a provider outage fail the test exactly as they would fail in production.

Costs and data

Calls are shown in AI usage and costs on the Connections page (administrators only), split by origin: workflows, prompt tuning and mailbox analysis. Only gpt-5-nano has a known price; other models are counted in calls and tokens, without a cost.

The content of the emails processed by an AI node is sent to OpenAI.

Common errors

Errors are reported by a stable code; the interface translates it. On the Connections page, the reason for a failed Test or model list appears in the provider card, and other refusals (saving, deleting) in a banner at the top of the section; during a run, the code appears in the step’s error. See also Error handling and replay and the error code reference.

Code	Cause	What to do
llm.invalid_api_key	The provider refused the key (HTTP 401 or 403): revoked, mistyped, or lacking access.	Create a new key at the provider, paste it in the card and Save, then Test. The run is not retried.
llm.rate_limited	The provider answered 429, 502, 503, 504 or 529 (quota, credits or overload), or the instance’s own limit (LLM_MAX_REQUESTS_PER_MINUTE, 60 calls per minute per provider by default) is reached.	Nothing to do for a passing peak: the step is postponed and resumed without using up a retry. If it persists, check your quota or credits at the provider.
llm.timeout	The provider did not answer within LLM_REQUEST_TIMEOUT_MS (120 seconds by default).	Retried automatically. For long drafts on a slow server, raise the timeout.
llm.provider_unavailable	Network error, or another 5xx answer from the provider.	Retried automatically with backoff. Check the provider’s status if it persists.
llm.provider_rejected	The provider refused the request itself (HTTP 400, 404 or 422): unknown model id, input too long, schema refused.	Check the model id in the provider node or the enabled models. The run is not retried.
llm.model_not_allowed	The model named by the node is not enabled on the connection used.	Tick the model in the card, or name an enabled model in the provider node.
llm.no_default_model	No model can be chosen for this purpose: no recommended model at this provider and no enabled model. Also returned by Test when there is no model to test with.	Enable at least one model on the connection, or name the model in the provider node.
llm.no_provider_configured	No AI connection exists on the instance.	An administrator adds a connection on the Connections page.
llm.provider_not_configured	A provider node is linked to a provider that has no connection, or the first save was sent without a key.	Configure the provider, or link a provider node of a configured provider.
llm.connection_not_found	The connection selected in the provider node has been deleted.	Pick another connection in the node’s Connection field, then publish again.
llm.connection_provider_mismatch	The connection selected in the node belongs to another provider than the node.	Pick a connection of the right provider, or replace the provider node.
llm.invalid_json	The model returned unusable JSON for a structured output, even after one automatic repair.	Run again, or use a more capable model for this node.
llm.output_truncated	The structured answer was cut off by the output token ceiling.	Ask for less, or raise LLM_DEFAULT_MAX_OUTPUT_TOKENS (4,096 by default).
llm.empty_output	A reasoning model spent its whole budget reasoning and wrote nothing.	Run again, or use another model for this node.
llm.content_refused	The model refused to answer this content.	Review the prompt or the input. The run is not retried.
llm.connection_in_use	Deletion refused: published workflows use the connection (their names are listed).	Change their connection first, or confirm the deletion a second time.
llm.connection_is_default	Deletion refused: this is the provider’s default connection and others exist.	Click Make default on another connection, then delete this one.
llm.connection_label_taken	Another connection already uses this label.	Choose another label.
llm.encryption_disabled	The instance has no ENCRYPTION_KEY: it cannot store a secret.	Set the variable and restart the instance.
llm.discovery_failed	The model list could not be read: unexpected answer from the provider.	Check the key, the URL and the provider’s status, then try Show available models again.

Nodes that use this connection

• OpenAI (GPT) — llm.openai