AI models

Use a MailSlurp model ID to choose the evaluator for email and SMS matching, assertions, and structured extraction. Set aiOptions.model on your request, or omit it to use the default, BALANCED_V1.

Supported model IDs

Use one of these public MailSlurp IDs in aiOptions.model:

Model ID	Selection guidance
BALANCED_V1	Default for message matching, assertions, and extraction when model selection is omitted.
FLASH_LATEST	Moving alias. Its implementation can change; evaluate your test cases when comparing results over time.
QUALITY_V1	Versioned model ID. Check the model catalog for availability before selecting it.

A model ID in the schema is a valid selector, but availability depends on the models enabled in the API environment you call. Check the model catalog before selecting a different model. An unavailable model produces an error; it does not silently switch to another model.

Check available models

Call GET /ai/models with your API key to discover the enabled models. This command prints only their MailSlurp IDs:

curl --fail --silent --show-error \
  'https://api.mailslurp.com/ai/models' \
  -H "x-api-key: $MAILSLURP_API_KEY" \
  | jq -r '.[].model'

The catalog also reports supportedMessageTypes, movingAlias, and tokenMultiplier. Use those fields when checking whether a model supports your message type and how it consumes your AI allowance. Read current values from the catalog rather than assuming that every model has the same multiplier.

With a current JavaScript SDK, use aiController.getAIMessageModels() and the public model enum:

import { MailSlurp, AIMessageAIOptionsModelEnum } from 'mailslurp-client';

const mailslurp = new MailSlurp({ apiKey: process.env.MAILSLURP_API_KEY! });
const model = AIMessageAIOptionsModelEnum.BALANCED_V1;
const available = await mailslurp.aiController.getAIMessageModels();
const enabledIds: string[] = available.map((item) => item.model);
if (!enabledIds.includes(model)) {
  throw new Error(`The requested MailSlurp model is unavailable: ${model}`);
}
const aiOptions = { model };

Use aiOptions in the operation's request options. If your installed SDK does not export AIMessageAIOptionsModelEnum or getAIMessageModels, update mailslurp-client or call the REST endpoint directly.

Select a model for extraction

This request extracts an OTP from an existing email. Replace EMAIL_ID with the email's resource ID; for SMS, set message.type to SMS and supply the SMS resource ID.

{
  "message": {
    "type": "EMAIL",
    "id": "EMAIL_ID"
  },
  "extractionPreset": "OTP_CODE",
  "aiOptions": {
    "model": "BALANCED_V1",
    "maxTokens": 8000,
    "maxOutputTokens": 2048
  }
}

Send it to POST /ai/messages/extract. Model selection uses the same top-level aiOptions on the message wait, assertion, and expectation operations. For an AI condition added to an existing email or SMS wait, configure ai.aiOptions in the wait's match or condition options instead. On /ai/messages/wait, keep the evaluator settings in the top-level aiOptions; do not supply conflicting settings in match.aiOptions.

See the AI workflow documentation for complete requests, extraction schemas, evidence, and failure handling, and wait conditions for adding a semantic match to an existing wait.

Choose and compare models in tests

Start with the default model and a representative set of messages from your application. Include missing codes, ambiguous content, localized templates, and messages that should not match. Compare the returned status and evidence as well as the extracted value.

For repeatable test configuration, set the model ID explicitly. FLASH_LATEST is a moving alias, so its implementation can change over time. A versioned ID makes your selection explicit, but AI output still needs assertions and source evidence; identical inputs are not a guarantee of identical output.

Keep token limits and timeout handling in place when changing models. Treat INCONCLUSIVE as an outcome to handle, and avoid retrying with different models until a test happens to pass. For an OTP, check successful, the code's expected format, and its extraction evidence before entering it in a browser.

Model selection here applies to the message-testing APIs. For saved transformer workflows and their request options, see AI transformers and invoking transformers.