Schedule a broadcast

Schedule a broadcast to send at a time, or now.

POSThttps://app.usenotix.dev/api/v1/broadcasts/{broadcastId}/schedule

Needs a full access key. Sending access keys cannot call this. Key permissions lists the extra rules some calls have.

Schedule a broadcast to send at a time, or now. A broadcast still held for review answers 202.

At a sending limit

A broadcast that reaches a sending limit is accepted and held, not failed. It stays RUNNING with its place in the list kept (the dashboard shows "Paused: units used up", "Paused: free plan monthly limit", "Paused: daily limit" or "Paused: warm-up limit"), and carries on by itself when the limit allows again:

a paid plan's monthly units: when the units reset, or within a minute or two of an upgrade, switching on pay-as-you-go or a wallet top-up. Notix sends broadcast.paused_for_limit once per billing period;
the Free plan's monthly limit: at the start of the next month, or at once on an upgrade;
the daily limit, or a new domain's warm-up cap: after 00:00 UTC.

While held, Notix looks again about every 30 minutes.

Approval

Every API key has an approval policy, set by a team admin. Keys created before policies existed use the default, APPROVE_OVER_N with N = 50. An admin can turn approval off for a key in the dashboard; that key then schedules without approval and reports its policy as null.

Policy	What a schedule by the key does
`APPROVE_OVER_N` (the default, N = 50)	Up to N recipients sends. Above N it answers 409 `APPROVAL_REQUIRED` with a draft card in `approval`, and emails a 6-digit code to the key's owner and the team's admins. Show `approval.card` to the person, ask them for the code, send it to `POST /v1/broadcasts/{broadcastId}/approve`, then schedule again with `approvalId`.
`AUTO_UNDER_N`	Up to N recipients sends. Above N it answers 403: send it from the dashboard.
`DRAFT_ONLY`	Every schedule answers 403. The key only saves drafts.

A person must approve: the agent never receives the code, and a schedule only uses an approval a person approved (by the code, or by Approve on the broadcast in the dashboard), presented by approvalId, at least 10 seconds after it was created. A key may send at most 20 approved broadcasts in 24 hours, and ask for at most 10 new approvals an hour. An approval is single use, expires after 24 hours and is bound to the broadcast, its content and the recipient count on the card. The send is capped at that count: contacts added afterwards are not reached. A changed broadcast or count answers 409 again with a new card. A create with sendNow or scheduledAt goes through the same check and keeps its draft when it answers 409.

Idempotency

Pass an Idempotency-Key header to make a retry safe for 24 hours. The same key and body answers the original result without sending again, with the response header Idempotent-Replayed: true. The same key with a different body answers 409 NOT_UNIQUE; the same key while the first request is still running answers 409 too, so retry shortly. Keys are scoped to the API key.

Dry run

Send the header Notix-Dry-Run: true to see what the request would do without doing it. The answer is 200 with dryRun: true: who it would reach, what they would see, what it would cost, a verdict (allowed and every reasons it would be refused for) and the limits it would count against. Nothing is sent, charged, reserved or written, and the call is recorded in the audit log as a dry run. A write route that cannot preview answers 400.

Path parameters

broadcastIdstringrequired

Body parameters

scheduledAtstring

Timestamp in ISO 8601 format or natural language (e.g., 'tomorrow 9am', 'next monday 10:30')

batchSizeinteger

Minimum 1. Maximum 100000.

maxRecipientsinteger

The most recipients this campaign may reach. Scheduling is refused (422 RECIPIENT_CAP_EXCEEDED) when the audience is larger. Whether or not you set it, a campaign never reaches more recipients than the count it was scheduled with.

Minimum 1.

approvalIdstring

The approval.approvalId from a 409 APPROVAL_REQUIRED, once a person has approved it (the emailed code through POST /v1/campaigns/{campaignId}/approve, or the dashboard). Single use, bound to this campaign, its content and the recipient count on the card.

Headers

Authorizationstringrequired

Bearer followed by your API key.

Idempotency-Keystring

Makes the request safe to retry for 24 hours. Same key and same body answers the original result without running again, with the response header Idempotent-Replayed: true. Same key and a different body answers 409 NOT_UNIQUE; same key while the first request is still running answers 409 too, so retry shortly. Keys are scoped to the API key.

Notix-Dry-Runstring

Set to true to preview the request instead of running it. The answer is 200 with dryRun: true: who it would reach, what they would see, what it would cost, whether policy allows it and the limits it counts against. Nothing is sent, charged, reserved or written. A write route that cannot preview answers 400.

Errors

403

The API key's approval policy refuses this schedule outright: DRAFT_ONLY keys only save drafts, and AUTO_UNDER_N keys may only send campaigns at or under their threshold. Send it from the dashboard.

409

APPROVAL_REQUIRED: the API key's approval policy needs a person's yes for a campaign this large. Nothing was sent; a POST /v1/campaigns with sendNow or scheduledAt kept its draft. A 6-digit code was emailed to the key's owner and the team's admins (never returned here). Show `approval.card` to the person, ask them for the code, send it to POST /v1/campaigns/{campaignId}/approve with `approvalId`, then schedule again with `approvalId`. A team admin can instead approve in the dashboard. The approval is single use, expires after 24 hours, can be used 10 seconds after it was created at the earliest, and caps the send at `approval.recipients`; a changed campaign or recipient count needs a new one.

Every error has the same shape. See all error codes.

curl -X POST "https://app.usenotix.dev/api/v1/broadcasts/<broadcastId>/schedule" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduledAt": "string",
  "batchSize": 1,
  "maxRecipients": 1,
  "approvalId": "cm1x8f3k20001qz7v5b9d2e4a"
}'

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.broadcasts.schedule("cmp_123", {
  scheduledAt: "2026-10-01T09:00:00Z",
  batchSize: 1000,
});

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

result, _ = notix.campaigns.schedule("cmp_123", {"scheduledAt": "2026-10-01T09:00:00Z", "batchSize": 1000})

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$result = $notix->campaigns->schedule('cmp_123', ['scheduledAt' => '2026-10-01T09:00:00Z', 'batchSize' => 1000]);

Response200

{
  "success": true
}

Open in Claude Open in ChatGPT