MagicDoorAPI
SupportOpen MagicDoor
Announcements

Schedule an announcement

Records an announcement to be sent at a future time. Nothing goes out until then.

POST
https://api.portal.magicdoor.com/company-app/announcements/schedule

Authorization

Authorizationstringrequired
Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Body

application/json

The same body as sending, except that scheduledSendAt is required.

subjectstring

The email subject line. 1 to 250 characters.

example: Water shut-off Thursday
chatMessagestring

The text to post into each recipient's chat, and to send as an SMS when sendText is on. 1 to 5,000 characters.

emailMessagestring

The body of the email to send. 1 to 30,000 characters. Leave it out to send no email.

sendTextboolean

Send chatMessage as an SMS as well as posting it into the chat.

default: true
tenantIdsstring[]

Send to these tenants. Exactly one of tenantIds, leaseIds, ownerIds, or vendorIds must be given.

leaseIdsstring[]

Send to these leases. Each lease's chat is one conversation shared by its tenants, so one message reaches them all.

ownerIdsstring[]

Send to these owners.

vendorIdsstring[]

Send to these vendors.

chatAttachmentSessionIdsstring[]

Upload sessions to attach to the chat message. At most 5.

emailAttachmentSessionIdsstring[]

Upload sessions to attach to the email. At most 5.

documentTemplateIdsstring[]

Letter templates to render per recipient and attach as PDFs.

scheduledSendAtstring · date-timerequired

When to send instead of now. Must be in the future.

chatAttachmentFilesstring[]deprecated

File ids to attach to the chat message.

emailAttachmentFilesstring[]deprecated

File ids to attach to the email.

Response

200 · The scheduled announcement. Its `status` is `pending` and `sentAt` is the time it is due.

idstring

The announcement.

companyIdstring

The company that sent it.

subjectstring

The subject line used for the email. Up to 250 characters.

chatMessagestring

The text posted into each recipient's chat and sent as an SMS.

emailMessagestring

The body of the email that was sent.

sendTextboolean

Whether the chat message was also sent as an SMS.

sentAtstring · date-time

When the announcement went out, or is due to go out if it is still scheduled.

statusenum<string>

pending means it is scheduled and has not gone out yet. partiallyFailed means some recipients got it and some did not.

pendingsentpartiallyFailedfailed
failureReasonstring

How many recipients failed, when any did. Absent on a clean send.

chatAttachmentsFile[]

Files attached to the chat message and the SMS.

emailAttachmentsFile[]

Files attached to the email.

targetsobject

Who it went to.

400 · `scheduledSendAt` is missing or not in the future, more or fewer than one recipient list was given, or a placeholder in the message text is not valid for this kind of recipient.

401 · The access token is missing, expired, or not valid.

This will deliver messages to real people, later

Nothing goes out while you are making this call, but at scheduledSendAt every recipient gets the announcement in their chat, by email, and by SMS, exactly as an immediate send would.

Scheduling creates a notification schedule alongside the announcement. It appears in the notification schedules list with a source of manual and a status of pending, and that is where you cancel it — delete the schedule before its time arrives.

MagicDoor sweeps for due schedules during the company's working hours, so an announcement scheduled for the middle of the night goes out at the start of the next working sweep rather than exactly on the minute.

Placeholders

chatMessage and emailMessage may contain letter-template placeholders. MagicDoor checks them against the kind of recipient you are sending to before anything goes out, and rejects the whole call with a 400 naming the placeholders it does not recognise.