Operator guide

AI writing assists

AI is optional and disabled on a new installation. Without an enabled provider, no AI controls appear and the AI API routes return 404; the rest of the builder works normally.

Configure a provider

Sign in as an operator Owner or Admin, open Settings → AI, and choose either an OpenAI-compatible Chat Completions provider or Anthropic Messages. Enter the model and API key. OpenAI-compatible providers also require their HTTPS base URL. Save, then use Test connection.

Test connection runs a real structured-output round trip, not just a ping. It asks the model for a small JSON object, reports which mode worked (a JSON schema, plain JSON mode, or plain text that Mailnib parses itself), and remembers it so later requests start there. Changing the provider, model or base URL clears the remembered mode; test again after any of those.

If a request fails, the message the customer sees ends with a reference such as Reference 3f9a1c2e. Search the application log for that reference to find the provider, model, HTTP status and finish reason. The log never contains the prompt, the reply or the key.

Reasoning models spend output tokens thinking and can run out before they answer. The error then says so. Pick a non-reasoning model, or raise Output token limit (for example to 8000); it applies to every AI request as a minimum.

The key is encrypted with the installation's APP_KEY. The console shows only its last four characters and never returns the key or encrypted value to a browser. Keep APP_KEY backed up: losing it makes every sealed provider credential unreadable.

Image generation

Image generation is a separate, optional setting. It stays off until an image model is saved and its own test passes.

Under Settings → AI → Image generation, enter an image model such as gpt-image-1. By default it uses the OpenAI-compatible Base URL and API key you saved above, calling /images/generations on that Base URL. To use another provider, enter an Image Base URL and an Image API key; an Anthropic text provider has no image endpoint, so it always needs both. Save, then choose Test image generation. The test generates one small image and checks that it is a usable PNG, JPEG, GIF, WebP or AVIF file, so it uses one image from your provider account. The badge reads Ready once it passes. Changing the image model, either Base URL or either key makes the earlier test stale, and customers lose the feature until you test again. The image key is encrypted with APP_KEY like the text key and is included when you rotate it.

Each plan has an AI images per month allowance next to AI requests per month, edited the same way: 0 turns image generation off for that plan, and an empty limit is unlimited. The shipped defaults are Free 0, Starter 10, Professional 60 and Agency unlimited. Images are counted separately from text requests. A generation that fails, or whose result cannot be stored, is not counted.

In the editor, selecting an image shows Generate with AI in the inspector and on the image itself while it still holds a placeholder or template photo. The prompt is filled in from the image's alt text, the section's heading, the workspace name and the brand voice; the person edits it and picks wide, square or tall (chosen from the slot's size). The server asks the provider for the image, then treats the result exactly like an upload: it must be a real image within the size and pixel limits, it is re-encoded, and it is stored in the workspace's Media library, counted against the storage allowance. The Media library marks it AI generated and can filter on that. It is placed in the slot with the prompt as its alt text as one undoable edit. When the plan has no image allowance, or the install has no tested image model, the control is shown disabled with the reason and, for a plan limit, a link to the plans.

Images that a provider returns by URL are downloaded through the same guarded outbound client as every other provider call, which refuses private addresses and plain HTTP. Image requests wait up to 90 seconds.

Allowances and limits

Each plan has an AI requests per month allowance. 0 disables AI for that plan and an empty/unlimited limit has no monthly ceiling. The shipped defaults are Free 0, Starter 50, Professional 300, and Agency unlimited. A separate per-user requests-per-minute setting limits bursts. Usage is counted per workspace and calendar month.

What customers can do

Customers can draft or rewrite selected copy, shorten it, change its tone, request five subject/preheader pairs, and create alt text for a stored image when the selected model accepts images. Generated writing is always treated as plain text, never HTML. Images are loaded from workspace storage by the server; the browser cannot ask the provider to fetch an arbitrary URL.

Customers can also choose Describe your email from the Designs page, or use the one-line Describe an email and AI drafts it row at the top of the template chooser, which opens the brief in place and leaves the templates in view. When the workspace's plan does not include AI, the row says so and links to the plans; when AI is not configured for the install, nothing AI-related appears. Mailnib starts from the template library. The model first picks the closest finished template from a list of each template's name, category and description, then rewrites that template's headings, paragraphs, button labels and links, and image descriptions. The layout always comes from a hand-designed template; the server applies the model's edits only to text that already exists, validates the result, and uses the workspace's brand kit colours and fonts when it has one. When no template fits, the model answers "none" and Mailnib falls back to a validated outline of two to eight sections composed from the built-in element presets. Either way the provider returns JSON, never markup; the design is validated, counted against the normal design quota, and opened in the editor. If the first outline is malformed, Mailnib asks the provider to correct it once and then returns a clear error rather than saving a partial design. A running request can be cancelled from the progress view.

Every writing request also carries what the model needs to fit the email: the block's role (heading, paragraph, button text), the email's subject, its other headings, the workspace name, and the brand kit, including an optional Brand voice of up to 500 characters that customers write on the Brand kit page. The brief and the brand voice are treated as untrusted text. With a heading selected, Write a heading drafts one; with a button selected, the sparkle button next to Label writes the button text.

In the editor's Page tab, Suggest returns five subject and preheader pairs. Choosing a pair applies both fields together as one undoable edit.

Provider calls run during the HTTP request and time out after 20 seconds. There is no queue, background worker, Redis dependency, or retry job.

AI_STUB=1 selects the deterministic test adapter for browser automation. It never makes a provider request and is deliberately refused when NODE_ENV=production; do not use it as an installation setting.

Privacy

Only the text needed for the selected assist is sent, capped at 12,000 characters. For alt text, the stored image bytes are sent. Tell workspace users which provider you configured and review that provider's data-retention terms before enabling AI.

AI settings reference

The API key is encrypted and never sent back to the browser. Leave its field blank to keep the saved key. The per-user rate ceiling applies in addition to each workspace plan's monthly allowance. Test the configured provider before enabling it for customers.