The OpenAI API integration connects ThunderAI directly to OpenAI's servers using an API key.
Compared to the web interface, it is faster, more reliable, and gives you explicit control over which model you use.

Prerequisites

• An OpenAI account with API access enabled
• A valid API key
• Thunderbird with ThunderAI installed

Note: OpenAI API usage is billed separately from a ChatGPT subscription. Even if you have ChatGPT Plus, you still need to add credits to your API account.

Getting an API key

1. Go to platform.openai.com/api-keys
2. Click Create new secret key
3. Give it a name (e.g. "ThunderAI") and click Create
4. Copy the key immediately, it will not be shown again

Setup

The quickest way is the Setup Wizard: open it from the ThunderAI welcome page, the toolbar popup or the settings page, choose ChatGPT OpenAI API, paste your API key, choose a model and test the connection. The wizard then lets you turn on the AI features you want.
To set it up by hand, follow the steps below.

1. Open the ThunderAI settings

In Thunderbird, go to Tools → Add-ons and Themes → ThunderAI → Preferences.

2. Select the OpenAI API integration

In the Connection Settings panel, choose ChatGPT OpenAI API in the Connection Type dropdown.

3. Enter your API key

Paste your API key in the ChatGPT API Key field. The key is stored locally in Thunderbird and never sent anywhere other than OpenAI's servers.

4. Choose a model

Click Update list next to ChatGPT Models. The first time, Thunderbird asks for permission to access openai.com: accept it, or ThunderAI cannot reach OpenAI. Then select the model you want to use from the list.

5. Test the connection

Settings are saved as soon as you change them: there is no Save button.
Click Test now in the bar below the connection settings. When everything is fine, it shows "Connected — ChatGPT OpenAI API reachable". Then open any email, click the ThunderAI toolbar button and run a prompt.

Advanced options

Click Advanced options in the Connection Settings panel to show the settings below. Leave them empty or on Default to let the API decide. They adapt to the selected model: a setting the model does not accept is disabled, with a note that explains why. The saved value is kept, in case you switch back to another model.

• Temperature and Top P: how random or focused the answer is. The reasoning models do not accept them: use Reasoning effort instead.
• Reasoning effort and Reasoning summary: how much the model reasons, and whether to show a summary of its reasoning in the chat. Reasoning models only.
• Verbosity: how long and detailed the answer is, on the models that support it.
• Max output tokens: the maximum length of the answer.
• Developer Messages: instructions and context sent to the model with every prompt.
• Output format: plain text (default), a JSON object, or JSON that follows a schema you enter.
• Truncation, Service tier, Prompt cache key, Safety identifier and Include encrypted reasoning: OpenAI request options, described in the OpenAI API reference.
• Use storage: if checked, OpenAI stores your chats.
• Extra body data: additional parameters as a JSON object, for options ThunderAI does not show.

You can also set these options on a single prompt, in the custom prompts page, and on each AI feature (Add Tags, Spam Filter, Summarize, Translate, Calendar Event, Task), with the Advanced options button of its specific connection.

Tips

• API usage is measured in tokens. Emails are typically short, so costs are usually very low. Check your usage at platform.openai.com/usage.
• OpenAI regularly adds new models. Click Update list to see the latest available.
• If OpenAI's rate limit or quota is exceeded while ThunderAI processes several emails (Add Tags, Spam Filter, Summarize, Translate), the processing stops by itself and tells you how many messages were processed.

Troubleshooting

"Authentication failed — check your API key" or "Invalid API key" error

Double-check that you copied the key correctly — there should be no extra spaces. If the key still fails, generate a new one from the OpenAI platform.

"You exceeded your current quota" error

Your OpenAI API account has run out of credits. Add more at platform.openai.com/settings/organization/billing.

No models appear in the list

If you see "You have denied the optional permission needed to fetch models for this integration", click Update list again and accept Thunderbird's permission request. Otherwise make sure your API key is valid and check your internet connection.

The popup asks for a permission instead of showing the prompts

The openai.com permission has not been granted yet. Click the message in the popup: the ThunderAI welcome page opens. Click the same message there and accept Thunderbird's request. You can also grant it from step 4.