Send an announcement
Sends one message to a set of tenants, leases, owners, or vendors at once, by chat, email, and SMS. It goes out immediately.
Authorization
AuthorizationstringrequiredBody
application/json
Give exactly one of tenantIds, leaseIds, ownerIds, or vendorIds.
subjectstringThe email subject line. 1 to 250 characters.
chatMessagestringThe text to post into each recipient's chat, and to send as an SMS when sendText is on. 1 to 5,000 characters.
emailMessagestringThe body of the email to send. 1 to 30,000 characters. Leave it out to send no email.
sendTextbooleanSend chatMessage as an SMS as well as posting it into the chat.
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-timeWhen to send instead of now. Must be in the future.
chatAttachmentFilesstring[]deprecatedFile ids to attach to the chat message.
emailAttachmentFilesstring[]deprecatedFile ids to attach to the email.
Response
200 · The announcement, with the outcome in `status`.
idstringThe announcement.
companyIdstringThe company that sent it.
subjectstringThe subject line used for the email. Up to 250 characters.
chatMessagestringThe text posted into each recipient's chat and sent as an SMS.
emailMessagestringThe body of the email that was sent.
sendTextbooleanWhether the chat message was also sent as an SMS.
sentAtstring · date-timeWhen 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.
failureReasonstringHow 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.
targetsobjectWho it went to.
400 · More or fewer than one recipient list was given, `scheduledSendAt` is not in the future, 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.
Every tenant, lease, owner, or vendor you list gets the announcement posted into their MagicDoor chat, emailed to them when you supply emailMessage, and sent as an SMS when sendText is on — which it is unless you turn it off. Preview the recipients first if you are not certain who they are.
chatMessage is posted into the recipient's chat, and sent as an SMS too when sendText is on. emailMessage is sent as an email with subject as its subject line. Supply whichever of the two you want; leaving one out skips that channel.
Sending to a lease posts one message into that lease's chat, which every tenant on the lease is in. It is not one message per tenant.
The call returns 200 even when some recipients could not be reached. Read status: sent means everyone got it, partiallyFailed that some did not, failed that nobody did. failureReason says how many.
A company with notifications switched off completely records the announcement and sends nothing.
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.
Passing scheduledSendAt here schedules the announcement instead of sending it, exactly as the schedule endpoint does.