Broadcasts

Returns the plan cadence, the next time you may send, and how many members would receive a broadcast. recipientCount counts members who accepted membership, have a verified email and opted in to broadcasts, among the first 200 memberships; recipientCountCapped is true when the account has more, so the real audience is larger. A single send reaches at most 5,000 recipients. cadenceDays is null on Worker Bee.

curl "https://app.hive3.tech/api/v1/broadcasts/audience?account=@design-guild" \
  -H "Authorization: Bearer $HIVE_API_KEY"

Returns 200.

{ "data": { "cadenceDays": 30, "maxRecipients": 5000, "nextAllowedAt": null, "recipientCount": 128, "recipientCountCapped": false } }

Errors: 403 insufficient_scope, 403 forbidden (your role on the account does not allow this), 404 not_found (account not found).

Lists the account's broadcasts, newest first. Pass page.nextCursor back as cursor (pagination).

curl "https://app.hive3.tech/api/v1/broadcasts?limit=10" \
  -H "Authorization: Bearer $HIVE_API_KEY"

Returns 200 with the broadcast fields above, without bodyText and bodyHtml, and a page object.

{
  "data": [{ "id": "broadcast_123", "accountId": "account_123", "subject": "November news", "status": "sent", "bodyMode": "editor", "heroImageUrl": null, "scheduledAt": null, "sentAt": "2026-10-12T15:00:00.000Z", "recipientCount": 128, "sentCount": 127, "failedCount": 1, "createdAt": "2026-10-11T09:30:00.000Z", "updatedAt": "2026-10-12T15:04:00.000Z" }],
  "page": { "nextCursor": null, "hasMore": false }
}

Returns one broadcast with its bodyText and bodyHtml. 404 not_found (Broadcast not found) when the ID does not exist; 403 forbidden when you may not manage the account that owns it.

curl https://app.hive3.tech/api/v1/broadcasts/broadcast_123 \
  -H "Authorization: Bearer $HIVE_API_KEY"

Returns 200 with the object shown under create.

Creates a draft. Plain text in bodyText becomes HTML paragraphs (a blank line starts a new paragraph) when you omit bodyHtml. HTML is cleaned the same way as in the app editor. The request body can be up to 400 KiB (413 above that). The route reads the Idempotency-Key header: repeating a create with the same key and body returns the first response, and the same key with a different body returns 409 conflict (idempotency).

curl -X POST "https://app.hive3.tech/api/v1/broadcasts?account=@design-guild" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: november-news" \
  -d '{"subject":"November news","bodyText":"Portfolio night is back.\n\nSee you on the 12th."}'

const res = await fetch("https://app.hive3.tech/api/v1/broadcasts?account=@design-guild", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIVE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "november-news",
  },
  body: JSON.stringify({ subject: "November news", bodyText: "Portfolio night is back.\n\nSee you on the 12th." }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://app.hive3.tech/api/v1/broadcasts",
    params={"account": "@design-guild"},
    headers={"Authorization": "Bearer " + os.environ["HIVE_API_KEY"], "Idempotency-Key": "november-news"},
    json={"subject": "November news", "bodyText": "Portfolio night is back.\n\nSee you on the 12th."},
)
data = res.json()["data"]

Returns 201.

{
  "data": {
    "id": "broadcast_123", "accountId": "account_123", "subject": "November news", "status": "draft", "bodyMode": "editor",
    "bodyText": "Portfolio night is back.\n\nSee you on the 12th.", "bodyHtml": "<p>Portfolio night is back.</p><p>See you on the 12th.</p>",
    "heroImageUrl": null, "scheduledAt": null, "sentAt": null, "recipientCount": 0, "sentCount": 0, "failedCount": 0,
    "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:00:00.000Z"
  }
}

Edits a draft. Send only the fields you want to change. If you change bodyText and omit bodyHtml, the HTML is rebuilt from the text. Only drafts can be edited: a scheduled, sending or sent broadcast returns 400 (Only draft newsletters can be edited); cancel a scheduled send first.

curl -X PATCH https://app.hive3.tech/api/v1/broadcasts/broadcast_123 \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"November news: portfolio night","heroImageUrl":null}'

const res = await fetch("https://app.hive3.tech/api/v1/broadcasts/broadcast_123", {
  method: "PATCH",
  headers: { Authorization: `Bearer ${process.env.HIVE_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ subject: "November news: portfolio night", heroImageUrl: null }),
});
const { data } = await res.json();

import os, requests

res = requests.patch(
    "https://app.hive3.tech/api/v1/broadcasts/broadcast_123",
    headers={"Authorization": "Bearer " + os.environ["HIVE_API_KEY"]},
    json={"subject": "November news: portfolio night", "heroImageUrl": None},
)
data = res.json()["data"]

Returns 200 with the updated broadcast (same shape as create). Errors: 400 invalid_request (limits, or the broadcast is not a draft), 403, 404 not_found, 413.

Emails the draft, with [Test] before the subject, to the primary email of the key owner. The address must be verified. It never goes to anyone else, and a test does not count toward your send cadence. Send no body.

curl -X POST https://app.hive3.tech/api/v1/broadcasts/broadcast_123/test \
  -H "Authorization: Bearer $HIVE_API_KEY"

Returns 200.

{ "data": { "sent": true } }

Errors: 400 invalid_request (Add a primary email to your account before sending a test broadcast, or Verify your primary email before sending a test newsletter when the address is not verified), 403, 404 not_found, 429 rate_limited after 10 tests in an hour.

Sends the broadcast to opted-in members now, or schedules it when you pass scheduledAt. The account that owns the broadcast must be on Honey Bee or above, and the plan sets how often it may send: one broadcast every 30 days on Honey Bee, 14 on Swarm and 7 on Royal Hive. Only members with an accepted membership, a verified email and broadcasts turned on receive it, up to 5,000 recipients. Only drafts can be sent, and a delivery that has started cannot be retried.

curl -X POST https://app.hive3.tech/api/v1/broadcasts/broadcast_123/send \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt":"2026-11-02T15:00:00Z"}'

const res = await fetch("https://app.hive3.tech/api/v1/broadcasts/broadcast_123/send", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.HIVE_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ scheduledAt: "2026-11-02T15:00:00Z" }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://app.hive3.tech/api/v1/broadcasts/broadcast_123/send",
    headers={"Authorization": "Bearer " + os.environ["HIVE_API_KEY"]},
    json={"scheduledAt": "2026-11-02T15:00:00Z"},
)
data = res.json()["data"]

Returns 200 with the broadcast. A scheduled send has status scheduled and scheduledAt set; sending now returns status sending with sentAt set and counters at 0.

{
  "data": {
    "id": "broadcast_123", "accountId": "account_123", "subject": "November news", "status": "scheduled", "bodyMode": "editor",
    "bodyText": "Portfolio night is back.\n\nSee you on the 12th.", "bodyHtml": "<p>Portfolio night is back.</p><p>See you on the 12th.</p>",
    "heroImageUrl": null, "scheduledAt": "2026-11-02T15:00:00.000Z", "sentAt": null, "recipientCount": 0, "sentCount": 0, "failedCount": 0,
    "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:10:00.000Z"
  }
}

Cancels a scheduled send and returns the broadcast to draft, so you can edit it or schedule it again. Send no body.

curl -X POST https://app.hive3.tech/api/v1/broadcasts/broadcast_123/cancel \
  -H "Authorization: Bearer $HIVE_API_KEY"

Returns 200 with the broadcast, now draft with scheduledAt set to null. Errors: 400 invalid_request (Newsletter is not scheduled), 403, 404 not_found.