The broadcasts API from MagicBell — 2 operation(s) for broadcasts.
openapi: 3.0.3
info:
title: MagicBell apns broadcasts API
description: OpenAPI 3.0.3 Specification for MagicBell API.
contact:
name: MagicBell
url: https://magicbell.com
email: hello@magicbell.com
version: 2.0.0
servers:
- url: https://api.magicbell.com/v2
description: MagicBell REST API Base URL
tags:
- name: broadcasts
paths:
/broadcasts:
get:
tags:
- broadcasts
description: Retrieves a paginated list of broadcasts for the project. Returns basic information about each broadcast including its creation time and status.
operationId: list_broadcasts
parameters:
- name: page[size]
in: query
required: false
schema:
type: integer
- name: page[after]
in: query
required: false
schema:
type: string
- name: page[before]
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ArrayOfBroadcasts'
post:
tags:
- broadcasts
description: Creates a new broadcast message. When a broadcast is created, it generates individual notifications for relevant users within the project. Only administrators can create broadcasts.
operationId: create_broadcast
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Broadcast'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Broadcast'
/broadcasts/{broadcast_id}:
get:
tags:
- broadcasts
description: Retrieves detailed information about a specific broadcast by its ID. Includes the broadcast's configuration and current status.
operationId: fetch_broadcast
parameters:
- name: broadcast_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Broadcast'
components:
schemas:
user:
type: object
allOf:
- anyOf:
- required:
- email
type: object
properties:
email:
type: string
format: email
external_id:
pattern: \s*
type: string
- required:
- email
type: object
properties:
email:
type: string
format: email
external_id:
pattern: ^[^\s]+
type: string
- required:
- external_id
type: object
properties:
email:
type: string
format: email
external_id:
pattern: ^[^\s]+
type: string
- required:
- external_id
type: object
properties:
email:
type: string
format: \s+
external_id:
minLength: 1
pattern: ^[^\s]+
type: string
- minProperties: 1
type: object
properties:
custom_attributes:
type: object
email:
maxLength: 255
type: string
external_id:
maxLength: 255
type: string
first_name:
maxLength: 255
type: string
last_name:
maxLength: 255
type: string
phone_numbers:
type: array
items:
pattern: ^\+\d{1,3}\s?\d{1,14}$
type: string
additionalProperties: false
Links:
type: object
properties:
first:
type: string
next:
type: string
nullable: true
prev:
type: string
nullable: true
Broadcast:
required:
- title
- recipients
type: object
properties:
action_url:
maxLength: 2048
type: string
nullable: true
category:
maxLength: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
type: string
nullable: true
content:
maxLength: 10485760
type: string
nullable: true
created_at:
type: string
description: The timestamp when the broadcast was created.
format: date-time
readOnly: true
custom_attributes:
type: object
nullable: true
id:
type: string
description: The unique id for this broadcast.
overrides:
type: object
properties:
channels:
type: object
properties:
email:
type: object
properties:
action_url:
maxLength: 2048
type: string
nullable: true
content:
maxLength: 1048576
type: string
title:
maxLength: 255
minLength: 1
type: string
in_app:
type: object
properties:
action_url:
maxLength: 2048
type: string
nullable: true
content:
maxLength: 1048576
type: string
title:
maxLength: 255
minLength: 1
type: string
mobile_push:
type: object
properties:
action_url:
maxLength: 2048
type: string
nullable: true
content:
maxLength: 1048576
type: string
title:
maxLength: 255
minLength: 1
type: string
slack:
type: object
properties:
action_url:
maxLength: 2048
type: string
nullable: true
content:
maxLength: 1048576
type: string
title:
maxLength: 255
minLength: 1
type: string
sms:
type: object
properties:
action_url:
maxLength: 2048
type: string
nullable: true
content:
maxLength: 1048576
type: string
title:
maxLength: 255
minLength: 1
type: string
web_push:
type: object
properties:
action_url:
maxLength: 2048
type: string
nullable: true
content:
maxLength: 1048576
type: string
title:
maxLength: 255
minLength: 1
type: string
providers:
type: object
properties:
amazon_ses:
type: object
android:
type: object
ios:
type: object
mailgun:
type: object
postmark:
type: object
sendgrid:
type: object
slack:
type: object
additionalProperties: false
nullable: true
recipients:
maxItems: 1000
minItems: 1
type: array
items:
type: object
oneOf:
- $ref: '#/components/schemas/topic'
- $ref: '#/components/schemas/user'
status:
required:
- status
- summary
- errors
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
nullable: true
status:
enum:
- enqueued
- processing
- processed
type: string
readOnly: true
summary:
required:
- total
- failures
type: object
properties:
failures:
type: integer
description: The number of failures while processing the broadcast.
readOnly: true
total:
type: integer
description: The number of recipients that the broadcast was sent to.
readOnly: true
title:
maxLength: 255
minLength: 1
type: string
topic:
maxLength: 255
pattern: ^[A-Za-z0-9_\.\-/:]+$
type: string
nullable: true
example:
action_url: https://example.com
category: example
content: Hello, World!
custom_attributes: {}
id: d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b
overrides: {}
recipients:
- custom_attributes:
plan: enterprise
preferred_pronoun: They
pricing_version: v10
email: test@example.com
external_id: 83d987a-83fd034
first_name: Person
last_name: Doe
phone_numbers:
- +1 5005550001
title: Hello, World!
topic: example
topic:
required:
- topic
type: object
properties:
topic:
required:
- subscribers
type: object
properties:
subscribers:
type: boolean
additionalProperties: false
additionalProperties: false
ArrayOfBroadcasts:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Broadcast'
links:
$ref: '#/components/schemas/Links'
example:
data:
- action_url: https://example.com
category: example
content: Hello, World!
custom_attributes: {}
id: d1b3b3b3-3b3b-3b3b-3b3b-3b3b3b3b3b3b
overrides: {}
recipients:
- custom_attributes:
plan: enterprise
preferred_pronoun: They
pricing_version: v10
email: test@example.com
external_id: 83d987a-83fd034
first_name: Person
last_name: Doe
phone_numbers:
- +1 5005550001
title: Hello, World!
topic: example
links:
first: https://api.magicbell.com/v1/example
next: https://api.magicbell.com/v1/example?page[next]=abc
prev: null