---
title: "Run evaluators against an email agent"
method: POST
path: "/test_framework/v2/scenarios/run_scenarios_email/"
tags: ["Evaluators"]
---

# Run evaluators against an email agent

`POST /test_framework/v2/scenarios/run_scenarios_email/`

## Request

- Base URL: `https://api.cekura.ai`
- URL: `https://api.cekura.ai/test_framework/v2/scenarios/run_scenarios_email/`
- Auth: one of:
  - API key in header `X-CEKURA-API-KEY`
  - HTTP bearer
  - HTTP bearer

EMAIL RUN: Execute evaluators against an agent that communicates over email. Cekura sends an email to the agent's address and simulates the full conversation, receiving replies via inbound webhook.

The agent must have an `email_id` configured, or you can supply `agent_email` as a one-time override. The `agent_email` field takes precedence if both are set.

**Run-count:** total conversations = `len(scenarios) × frequency`.

**Inbound agents** (`agent.inbound=true`): Cekura sends the first email to the agent. **Outbound agents** (`agent.inbound=false`): the response includes `inbound_email` — the address your agent should email first to start the conversation.

**Polling for completion:** the response is the result itself — read its top-level `id` (`status: 'running'`). Poll `GET /test_framework/v1/results/{result_id}/` until `status` is `completed`, `failed`, `timeout` or `cancelled`. A result stays non-terminal until every run has ended, then becomes `completed` if any run completed — even if runs failed their checks or others errored. To gate, require `success_runs_count == total_runs_count` (`failed_runs_count` counts only completed runs that failed evaluation).

## Request body

- RunScenariosEmail
  - `agent_id` integer, nullable: ID of the agent to run against. Required if none of the scenarios have an agent.
  - `scenarios` integer[], required: List of evaluator IDs to run.
  - `frequency` integer, required: Number of times to run each scenario.
  - `calls_per_second` number, double, nullable: Most calls started per second for this run, a number from 0.1 to 4 (e.g. 0.5 starts one call every 2 seconds). Leave unset for no limit.
  - `agent_email` string, email, nullable: Override the agent's configured email address for this run.

## Response `200`

- RunScenarioResult
  - `id` integer: Unique identifier for the Result Example: `123`
  - `name` string, required: Name of the Result Example: `"Test Result 1"`
  - `agent` integer: ID of the AI agent that was tested Example: `123`
  - `agent_inbound` boolean: Whether the agent is configured for inbound calls (true) or outbound calls (false) Example: `true` or `false`
  - `status` 'running' | 'completed' | 'failed' | 'pending' | 'in_progress' | 'evaluating' | 'in_queue' | 'timeout' | 'cancelled' | 'scaling_up': Current status of the result * `running` - Running * `completed` - Completed * `failed` - Failed * `pending` - Pending * `in_progress` - In Progress * `evaluating` - Evaluating * `in_queue` - In Queue * `timeout` - Timeout * `cancelled` - Cancelled * `scaling_up` - Scaling Up
  - `success_rate` number, double: Percentage of runs that passed, 0 to 100
  - `run_as_text` boolean: Whether this test was run in text mode instead of voice mode Example: `true` or `false`
  - `is_cronjob` string: Whether this result was created by a scheduled cronjob Example: `true` or `false`
  - `runs` object: Run summaries for this result. For full run data including transcripts and metric scores, fetch the result detail endpoint — there `runs` is a dict keyed by run ID.
  - `created_at` string, date-time: Timestamp when this test result was created Example: `2021-01-01 00:00:00`
  - `updated_at` string, date-time: Timestamp when this test result was last updated

## Changes

- **2026-11-03** `a6fb6a739212`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cekura/apis/cekura-api/changes/test_framework/v2/scenarios/run_scenarios_email/post.md)

---

[API](https://skmtc.dev/cekura/apis/cekura-api.md) - [All operations](https://skmtc.dev/cekura/apis/cekura-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cekura/apis/cekura-api/revisions/a6fb6a739212?raw)