Skip to main content
Create a message with the Loyalty Messages API when you want to notify residents from a CRM, PMS, or other backend. Operators can also send from the Dashboard. Residents receive a OneMove push notification, a branded email, or both.

​
Prerequisites

Before you send messages, ensure you have:
  • Loyalty enabled on the account.
  • A secret key, or a restricted key with message permissions.
Your secret key can perform any action on your account, so only ever use it from your own server. Never put it in a browser, a mobile app, or a vendor’s client. If a secret key is ever exposed, roll it immediately.

​
Permissions

  • loyalty.messages.write — create and send messages
  • loyalty.messages.read — retrieve and list messages
A vendor that only sends messages typically needs loyalty.messages.write. Listing or polling a send needs loyalty.messages.read.

​
1. Create a message

POST a message with a recipient, title, and body. channels defaults to ["push"] when you omit it. channels and email_delivery were added in API version 2026-09-15. Pin that version, or send Yorlet-Version: 2026-09-15, to set channels and read email delivery. See API versioning.
Send a building broadcast
Response
Create returns status: "pending". Delivery runs in the background. To write to one customer instead:
Send to a customer
The customer must have an active tenancy on the account.

​
Parameters

  • title — shown to the recipient. Maximum 100 characters.
  • body — shown to the recipient. Maximum 500 characters.
  • recipient — type: "building" with building, or type: "customer" with customer.
  • channels — push, email, or both. Defaults to ["push"].
  • category — optional announcement, event, offer, or alert. Groups the message on the building noticeboard in OneMove.

​
2. Who is notified

Building broadcasts:
  • Push goes to active residents who use OneMove and have confirmed they live at the building.
  • Email goes to every active resident with an email address, including residents who do not use OneMove.
Customer messages:
  • Push requires the customer to use OneMove.
  • Email uses the customer email. They do not need to use OneMove.
Email-only sends do not appear in the OneMove inbox. Building broadcasts appear on the noticeboard once they are sent.

​
3. Poll until it is sent

Retrieve the message with the Retrieve API until status is sent or failed.
Retrieve a message
  • delivery summarises OneMove push attempts.
  • email_delivery summarises email attempts when email was requested, and is null otherwise.
  • failure_code is set when the message failed: no_onemove_user, no_device_tokens, no_email, or send_error.
  • sent_at is set when at least one push or email was delivered.
status is sent when either channel delivers, and failed only when neither does. You can also list messages.

​
Notes for integrators

  • Call from your backend after the occasion you are announcing, not from a vendor’s frontend.
  • Each successful push or email is billed at £0.02. Failed and skipped deliveries are not charged. See list pricing.
  • Operators who do not want to call this API can send from the Dashboard instead.