---
title: "Announcements"
description: "Create and update announcements with complete curl request examples."
lastModified: "2026-08-25"
---

**Collection path:** `events/{event_id}/announcements`

| Input | Type | POST | PATCH | Notes |
| :---- | :---- | ----: | ----: | :---- |
| `heading` | Scalar string | Required by the model | Optional | Announcement heading, at most 999 characters. |
| `content` | Scalar string | Required by the model | Optional | Announcement content, at most 99,999 characters. |
| `url` | Scalar string or `null` | Optional | Optional | Related URL. |
| `send_as_email` | JSON boolean | Optional | Optional | Email sending requires an organization-wide, unrestricted scope. |
| `target_list_ids` | Array of scalar IDs | Optional | Optional | Full replacement when supplied. `[]` removes list-specific targeting. |
| `delivery_mode` | Scalar string | Optional | Optional | `draft`, `immediate`, or `scheduled`. |
| `scheduled_at` | ISO 8601 string | Conditional | Conditional | Required when mode is `scheduled`. Supplying it without a mode implies `scheduled`. |

Released announcements are immutable and cannot be patched. Every target list must belong to the event.

## POST an announcement

```shell
curl --request POST \
  --url "${BRELLA_API_BASE_URL}/api/core/organizations/${BRELLA_ORGANIZATION_ID}/events/${BRELLA_EVENT_ID}/announcements" \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "heading": "Welcome reception",
    "content": "Doors open at 18:00.",
    "url": "https://example.com/reception",
    "send_as_email": false,
    "target_list_ids": [401, 402],
    "delivery_mode": "scheduled",
    "scheduled_at": "2026-09-03T15:00:00Z"
  }'
```

The created announcement starts unreleased. The response type is `announcement`; useful write-response fields include `heading`, `delivery_mode`, `scheduled_at`, `target_list_ids`, and `released`.

## PATCH an announcement

This example reschedules an existing unreleased announcement. Omitted heading, content, URL, email, and targeting values remain unchanged.

```shell
curl --request PATCH \
  --url "${BRELLA_API_BASE_URL}/api/core/organizations/${BRELLA_ORGANIZATION_ID}/events/${BRELLA_EVENT_ID}/announcements/7101" \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "delivery_mode": "scheduled",
    "scheduled_at": "2026-09-03T16:00:00Z"
  }'
```

Use `{"delivery_mode":"draft"}` to remove the scheduled job from an unreleased announcement. `immediate` schedules execution at the current time; it does not directly mark the record as released inside the PATCH request.