Safety

5 endpoints

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.
FieldTypeRequiredDescription
modestringrequired("test" | "production")
sourcestringrequired("use_case" | "project" | "org")
scopedbooleanrequired
orgDefaultstringrequired("test" | "production")
projectDefaultanyrequired
projectanyrequired
useCaseanyrequired
useCasesDifferingnumberoptional
useCasesobject[]optionalProject answer only: each active use case and its own mode (null = follows the project default).
require2faThresholdnumberrequired
testListMaxSizenumberrequired
canobjectrequiredWhether the caller may change this target and put it live: the checks PUT makes, judged on the target's project.
401Unauthorized
500Internal server error
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
FieldTypeRequiredDescription
modeanyrequired
useCaseIdstring (uuid)optional
projectIdstring (uuid)optional
applyToUseCasesbooleanoptional
liveUseCaseIdsstring[]optional
Responses
200The mode the target now resolves to.
FieldTypeRequiredDescription
modestringrequired("test" | "production")
sourcestringrequired("use_case" | "project" | "org")
orgDefaultstringrequired("test" | "production")
projectDefaultstringoptional("test" | "production")
useCasesResetnumberoptional
useCasesPinnedTestnumberoptional
400Invalid body: bad mode, both useCaseId and projectId, null outside a use case, or liveUseCaseIds naming a use case outside the project
401Unauthorized
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
500Internal server error
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.
FieldTypeRequiredDescription
listsobject[]required
usageobjectrequired
401Unauthorized
500Internal server error
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
FieldTypeRequiredDescription
namestringrequired
emailsstring[]optional
Responses
201The newly created test list.
FieldTypeRequiredDescription
listobjectrequired
400Missing or invalid list name, or a `projectId` in the body
401Unauthorized
409TEST_LIST_LIMIT_REACHED: the org tier's total address cap would be exceeded
500Internal server error
DELETE/api/safety/test-listsauth required

Delete a test email list

Deletes a test email list by ID. Requires safety.configure permission.

Parameters
NameInTypeRequiredDescription
idquerystringrequiredThe ID of the test list to delete.
Responses
200Deletion confirmed.
FieldTypeRequiredDescription
deletedbooleanrequired
400Missing list ID
401Unauthorized
500Internal server error