GET/api/safety/modeauth required
Get the send mode for a surface
Send mode is layered org → project → use case. With `useCaseId` (or `projectSlug` + `useCaseSlug`) returns the use case's mode — its own, or its project's default when it follows it. With `projectSlug` or `projectId` alone returns the project default. With neither, returns the org default: the mode new projects start in. `orgScope=1` reports the org mode for surfaces that send without a use case.
Responses
200The mode a send from this surface would use, and where it comes from.
| Field | Type | Required | Description |
|---|
| mode | string | required | ("test" | "production") |
| source | string | required | ("use_case" | "project" | "org") |
| scoped | boolean | required | |
| orgDefault | string | required | ("test" | "production") |
| projectDefault | any | required | |
| project | any | required | |
| useCase | any | required | |
| useCasesDiffering | number | optional | |
| useCases | object[] | optional | Project answer only: each active use case and its own mode (null = follows the project default). |
| require2faThreshold | number | required | |
| testListMaxSize | number | required | |
| can | object | required | Whether the caller may change this target and put it live: the checks PUT makes, judged on the target's project. |
PUT/api/safety/modeauth required
Update a send mode
With `useCaseId`, sets that use case's own mode (`mode: null` makes it follow its project default). With `projectId`, sets the project default; `applyToUseCases` also makes every use case in the project follow it; `liveUseCaseIds` (going live only, not with `applyToUseCases`) puts just those use cases on the live default and pins every other active use case in the project to test. With neither, sets the org default for new projects. Judged on the target's project (a project role, or an org role with org-wide project authority): a use case needs `send.test`, a project default `safety.configure`, and landing on production `send.production`. The org default needs both at org level.
Request Bodyrequired
| Field | Type | Required | Description |
|---|
| mode | any | required | |
| useCaseId | string (uuid) | optional | |
| projectId | string (uuid) | optional | |
| applyToUseCases | boolean | optional | |
| liveUseCaseIds | string[] | optional | |
Responses
200The mode the target now resolves to.
| Field | Type | Required | Description |
|---|
| mode | string | required | ("test" | "production") |
| source | string | required | ("use_case" | "project" | "org") |
| orgDefault | string | required | ("test" | "production") |
| projectDefault | string | optional | ("test" | "production") |
| useCasesReset | number | optional | |
| useCasesPinnedTest | number | optional | |
400Invalid body: bad mode, both useCaseId and projectId, null outside a use case, or liveUseCaseIds naming a use case outside the project
403No role on the target's project, or missing send.test (use case), safety.configure (project/org) or send.production (going live)
404Use case or project not found in this organization
409Refused moving to test: `PENDING_SCHEDULED_CAMPAIGNS` (a campaign is scheduled), `SCHEDULE_UNVERIFIED` (we could not confirm nothing is scheduled, e.g. a key without Marketing read access; the message names the fix), or `PRODUCTION_NOT_READY` going live
503`SCHEDULE_CHECK_UNAVAILABLE`: the provider did not answer the check for scheduled campaigns (rate limit, outage, network). Nothing changed; retry shortly
GET/api/safety/test-listsauth required
List test email lists
Returns the organization's test lists (the org tier: always on for every project) and the tier's usage. The cap is a total across all org lists. Requires safety.configure permission.
Responses
200All test email lists.
| Field | Type | Required | Description |
|---|
| lists | object[] | required | |
| usage | object | required | |
POST/api/safety/test-listsauth required
Create a test email list
Creates an organization test list with a name and optional email addresses. Fails when the org tier would exceed its total address cap. Project lists use /api/projects/{projectId}/safety/test-lists. Requires safety.configure permission.
Request Bodyrequired
| Field | Type | Required | Description |
|---|
| name | string | required | |
| emails | string[] | optional | |
Responses
201The newly created test list.
| Field | Type | Required | Description |
|---|
| list | object | required | |
400Missing or invalid list name, or a `projectId` in the body
409TEST_LIST_LIMIT_REACHED: the org tier's total address cap would be exceeded
DELETE/api/safety/test-listsauth required
Delete a test email list
Deletes a test email list by ID. Requires safety.configure permission.
Parameters
| Name | In | Type | Required | Description |
|---|
| id | query | string | required | The ID of the test list to delete. |
Responses
200Deletion confirmed.
| Field | Type | Required | Description |
|---|
| deleted | boolean | required | |