Send a test message on channel to to from the organization's sender as it stands

POST /notifications/test

Send a test message on channel to to from the organization's sender as it stands — an email address for email, a phone number in international form (+61 412 345 678) for sms — the way to see what recipients will see and that the sending domain or the SMS sender ID works.

Appends notifications.requested, then notifications.sent (with the provider's message id) or notifications.failed (with its reason). 400 RecipientInvalid when to does not fit the channel; 409 SenderNotConfigured until the sender is saved; for a text, 404 SmsSenderNotFound until a sender ID is saved and 409 SmsNotSendable when the number's country is not one it is active in; 409 RecipientSuppressed for an address that bounced for good, complained or opted out. Keyed on notificationId, the caller-minted ntf_ id: a retry answers the notification as recorded and never sends a second message.

Access

Requires notifications:write.

How scopes come from roles: Scopes and roles. Getting a token: Authentication and app tokens.

Retries

Keyed on notificationId, the caller-minted ntf_ id: a retry answers the notification as recorded and never sends a second message.

A retry with the same key answers 200, with what the first call recorded.

Why every write carries a key: Idempotency and retries.

Facts appended

notifications.requested
notifications.sent
notifications.failed

What a fact is: Facts and the journal.

AI agent tool

Agents call this as notifications_send_test (Notifications: Send test), in the notifications toolset.

Connecting an agent: AI agents.

Example

curl

curl -X POST 'https://notifications.getmanifold.io/notifications/test' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "notificationId": "ntf_01a157ae-4288-7f3b-bb14-41f2affd24eb",
  "channel": "email",
  "to": "ops@ridgeline-outdoor.example"
}'

JavaScript (fetch)

const response = await fetch("https://notifications.getmanifold.io/notifications/test", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "notificationId": "ntf_01a157ae-4288-7f3b-bb14-41f2affd24eb",
    "channel": "email",
    "to": "ops@ridgeline-outdoor.example"
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

Request body · application/json

{
  "notificationId": "ntf_01a157ae-4288-7f3b-bb14-41f2affd24eb",
  "channel": "email",
  "to": "ops@ridgeline-outdoor.example"
}

Response · 200 · application/json

{
  "id": "ntf_01a157ae-4288-7f3b-bb14-41f2affd24eb",
  "kind": "sending-test",
  "channel": "email",
  "status": "sent",
  "to": [
    "ops@ridgeline-outdoor.example"
  ],
  "cc": [],
  "from": "\"Ridgeline Outdoor\" <accounts@ridgeline-outdoor.example>",
  "replyTo": "accounts@ridgeline-outdoor.example",
  "subject": "Test message from Ridgeline Outdoor",
  "source": {
    "kind": "settings",
    "id": "sender"
  },
  "requestedBy": {
    "_tag": "user",
    "id": "usr_01a15709-7582-7646-b491-261a138f0650"
  },
  "requestedAt": "2026-10-20T05:40:11.000Z",
  "sentAt": "2026-10-20T05:40:12.000Z",
  "providerMessageId": "0108019a2b3c4d5e-01a1587e-cd9b-7f2a-9b3c-4d5e6f7a8b9c-000000",
  "steps": [
    {
      "status": "requested",
      "at": "2026-10-20T05:40:11.000Z"
    },
    {
      "status": "sent",
      "at": "2026-10-20T05:40:12.000Z"
    }
  ]
}

The panel writes this call in other languages. It does not send it: Manifold's APIs do not take calls from a web page on another site, so run the call from your own code or terminal. The whole API as OpenAPI: notifications-manager.openapi.json. Base URL https://notifications.getmanifold.io.

Errors

Every refusal is a status and a JSON body whose _tag names it. A refused call changes nothing.

`400`

Refusal	What it means	What to do
`RecipientInvalid` channel, to, reason	`to` does not fit the channel.	Fix the request. Sending it again unchanged gets the same answer.

`401`

Refusal	What it means	What to do
`Unauthorized` reason	The token is missing, expired or not one Manifold issued.	Get a fresh token and send the call again.
`TokenAlreadyUsed` tokenId	A single-use app token was already spent.	Mint a new token for this call.

`402`

Refusal	What it means	What to do
`SubscriptionRequired` status	The organization's subscription has lapsed, so writes are refused.	An owner settles billing. Reads still work meanwhile.

`403`

Refusal	What it means	What to do
`TenantRequired` userId	The token names no organization.	Choose the organization, then get a new token.
`ScopeRequired` required	The token's roles do not grant the scope this call needs.	Ask an owner or admin for a role that grants it.

`404`

Refusal	What it means	What to do
`SmsSenderNotFound` reason	No such record in this organization.	Check the id in the path or the body.

`409`

Refusal	What it means	What to do
`RecipientSuppressed` to, suppressionId, reason	The request was refused. `reason` says why.	Nothing changed. Read the record, then decide.
`SenderNotConfigured` reason	The organization has no sender set up for mail.	Set up a sending domain first.
`SmsNotSendable` to, country, reason	The request was refused. `reason` says why.	Nothing changed. Read the record, then decide.
`MirroredFromSource` source	This area is fed by your source system until the organization goes live.	Make the change in the source system, or go live first.

`503`

Refusal	What it means	What to do
`MailProviderUnavailable` reason	The mail provider did not answer, so nothing was sent.	Send the same request again, with the same key.
`RequestLogUnavailable` tokenId, reason	The service could not record the request, so it did nothing.	Send the same request again, with the same key.

How refusals work everywhere: Errors.

Used in

Send mail from your own domain, step 5: Send a test message
Send mail from your own domain, step 6: Retry the send
Send text messages under your own name, step 4: Send a test text