How to Set Up Messages and Notifications
Keepit sends messages and notifications on a partner's behalf — welcome emails, backup reports, quota warnings, and more. This guide walks through the full setup in the order you would normally follow it: configure or customise the messages your customers receive, check which languages are supported, optionally forward notifications to partner users (tokens), and work with the in-app mailbox. Each step is self-contained, so you can follow the whole path or jump to the part you need.
Overview
- Configure customer messages — enable, disable, or customise the messages your customers receive (optional).
- Set up supported languages — define which languages an account's messages are available in (required).
- Set up forwarding — route a customer account's notifications to partner users (tokens) (optional).
- Work with the in-app mailbox — list, read, and delete messages in a user's mailbox.
All requests require HTTP Basic authentication and the standard API headers. See the Authentication and API Headers pages for details.
Step 1: Configure customer messages
This step is optional. Keepit enables a default set of messages for every account, inherited from the parent. Follow it only if you need to enable or disable specific messages for your customers, or customise their content.
Review which messages customers receive, inspect a message's current content, then enable or disable messages or customise their content as needed.
The {partnerId} in the path can be the partner or any account beneath it (a child partner or a customer). Lower accounts inherit each message's state from above unless it is set explicitly on that account, letting you override a single customer without affecting the rest.
List available messages
See the List messages page for details.
Returns every message available in the account's bundle and whether each is enabled. If a message's enabled state is inherited from a parent account, the response includes an <inherited> element identifying that account.
| Method | GET |
| Endpoint | /bl/partner/{partnerId}/messages |
| Body | none |
You can run the endpoint with the v0 or v1 header to get the full list of message types. Include the header Accept: application/vnd.keepit.v2+xml instead if you want the full v2 response with group, inheritance, and per-language details. The v2 response only includes message types that have been explicitly set somewhere in the hierarchy.
curl
Code
Example
Listing all available messages for a partner:
Code
Response
Code: 200 OK
Code
Inspect a specific template
See the Get message content page for details.
Returns the content of a specific message for a given language. If the template is set directly on this account, the response contains a <content> block only; if it is inherited, the response includes an <inherited> element identifying the source account, alongside the inherited <content>.
| Method | GET |
| Endpoint | /bl/partner/{partnerId}/messages/{name}/{language} |
| Body | none |
curl
Code
Example
Retrieving the English content for the first-backup-complete message:
Code
Response
Code: 200 OK
Code
Enable or disable a message
See the Update message page for details.
Turns a message on or off for whichever account you call this on, without changing its content. If you set it on a partner, it will be off for the partner itself and every subaccount still inheriting from it.
This uses the same endpoint as customising a message's content (below) — the body you send determines the action. Enabling or disabling a message is independent of the forwarding (toggle in Step 3).
| Method | PUT |
| Endpoint | /bl/partner/{partnerId}/messages/{name} |
| Body | XML <message> |
Send the following <message> body:
| Body field | Value |
|---|---|
enabled | true or false — or omit it (send an empty <message></message>) to clear the setting and inherit the state from the parent |
curl
Code
Example
Disabling the anomaly-detected message for the account:
Code
Code
Response
Code: 200 OK
Code
Customise a message's content
See the Update message page for details.
Sets custom content for one or more languages using the update block, which can be repeated once per language. Include enabled in the same call to set the on/off state at the same time.
To customize a message directly on an account, that account needs its own languages added (Step 2) — it doesn't matter whether you do that before or after customizing, but without it the change is saved and never delivered. Inherited messages are unaffected: they use the parent's languages, so you only need to add languages on accounts you customize directly.
This uses the same endpoint as enabling or disabling a message (above).
| Method | PUT |
| Endpoint | /bl/partner/{partnerId}/messages/{name} |
| Body | XML <message> |
Send the following <message> body:
| Body field | Value |
|---|---|
enabled | true or false — optional; sets the on/off state in the same call |
language | the language you're setting content for — a valid RFC 5646 tag (e.g. en-GB); repeat the update block once per language |
subject | the email subject line |
opening | greeting line, e.g. Dear <fullname/>, |
p | a body paragraph — repeat for multiple paragraphs |
closing | sign-off, e.g. Kind regards,<br/>Your Keepit Team |
Code
curl
Code
Example
Enabling the first-backup-complete message and setting its English content:
Code
Code
Response
Code: 200 OK
Code
Disable every message at once
A common case is silencing an account's default notifications entirely — for example, before setting up forwarding in Step 3 so that a different, chosen account gets notified instead. Do this by sending the same PUT call above once per message name (there are 53 in total — see the list below), with <enabled>false</enabled>, against the account you want silenced.
To silence all of a partner's subaccounts in one go, set it on the partner account itself instead. A customer account inherits its state from the nearest ancestor with an explicit setting, no matter how many levels up, so setting it on the partner silences every customer beneath it too, as long as none of them already have their own override.
Inheritance only flows down, never sideways. If more than one partner sits under the same root, repeat this on each partner you want silenced.
The full bundle is 53 message types — see the list below.
See all 53 message types
| Message | Description |
|---|---|
access-granted | The access was granted |
anomaly-detected | Unusual change detected in a backup snapshot |
approaching-consumption-quota | Nearing the consumption-based license limit |
approaching-seats-quota | Nearing the seat limit (sent at 70/80/90%) |
auto-add-stopped | Seat limit reached — new users can't be added automatically |
backup-failed | A backup was unsuccessful |
backup-incomplete | A backup finished incomplete |
backup-succeeded | A backup completed successfully |
broken-siem-connection-disabled | A SIEM integration was auto-disabled due to inactivity |
consumption-quota-violated | Over the consumption-based license limit |
data-compliance-report-complete | A compliance report is ready to download |
device-added | A new connector was added |
device-deleted | A connector was scheduled for deletion |
device-health-changed | A connector's health status changed |
device-resources-estimated | Estimated device resources |
disabling-automations-failed | Restore couldn't start — failed to disable required automations (e.g. Salesforce) |
feature-request | A customer submitted an upgrade/feature request |
feature-request-confirmation | Confirms an upgrade/feature request was submitted |
first-backup-complete | First backup finished successfully |
forgotpass | Password reset requested |
gracetime-expired | Account-level grace period has expired |
grant-access | Invitation email granting access |
invoice-paid | An invoice was paid |
multigeo-config-changed | The backup's geo-location setting changed |
payment-terms-violated | Payment terms were violated |
quota-hard | Hard storage quota reached |
quota-soft | Soft storage quota reached |
remotedrive-added | A remote drive was added |
report-complete-automated | Scheduled report for a single snapshot is ready to download |
report-complete-automated-aggregated | Scheduled report aggregating multiple snapshots is ready to download |
report-complete-manual | Manually requested report for a single snapshot is ready to download |
report-complete-manual-aggregated | Manually requested report aggregating multiple snapshots is ready to download |
resource-gracetime-expired | Grace period expired — connector can no longer back up that resource |
resource-gracetime-expires | Grace period ending soon (30/15/5 days) for over-quota usage |
restore-failed | A restore was unsuccessful; some items were skipped |
restore-incomplete | A restore finished incomplete; some items were skipped |
restore-started | A restore job was initiated |
restore-succeeded | A restore job completed successfully |
restore-with-disabled-automations-failed | Restore with disabled automations failed |
restore-with-disabled-automations-succeeded | Restore succeeded, but disabled automations need manual reactivation |
seats-quota-violated | Over the seat limit |
service-period-ended | Subscription has ended; account pending deletion |
service-period-ends | Subscription ending soon — renew to avoid a gap |
service-period-started | Welcome email for a limited-term service period |
sharepoint-backup-complete | SharePoint backup finished |
support-assignment-assigned | A support case was assigned |
support-assignment-response | Support case received a response |
support-ticket-closed | Support ticket was closed |
support-ticket-response | Support ticket received a response |
transform-complete | A data export (e.g. PST) is ready to download |
trial-service-period-ended | Trial/POC period ended; data will be deleted |
trial-service-period-started | Welcome email for a trial/POC period |
welcome | Welcome email for a new account, with an activation link |
Verify. Fetch List available messages with the Accept: application/vnd.keepit.v2+xml header, on the account you disabled and on a customer below it:
- The disabled account shows every message as
<enabled>false</enabled>. - Each customer below it, at any depth, shows an
<inherited>block pointing back to that account, still<enabled>false</enabled>. - If a customer instead shows its own direct
<enabled>value, it already had an override before you started, and inheritance can't reach past it — clear it with an empty body (see Enable or disable a message above), then re-check.
Step 2: Set up supported languages
This step is required for any customized message (Step 1) to actually be delivered — the account needs at least one language set, whether that happens before or after the customization.
If you're setting up forwarding (Step 3), it's the account that will receive the forwarded messages that needs a language here — it doesn't have to be the direct parent of the accounts being forwarded from, and it can sit several levels up. Accounts below it don't need one.
The {partnerId} in the path can be the partner or any account beneath it (a child partner or a customer) — whichever account you're setting languages for.
Configure supported languages
See the Get supported languages and Set supported languages pages for details.
Check which languages are already configured, then set the full list you want to support. Each language must be a valid RFC 5646 tag, and submitting the PUT replaces the current list entirely, so include every language you want to keep active.
| Method | GET / PUT |
| Endpoint | /bl/partner/{partnerId}/messages/languages |
| Body | none for GET; XML <languages> for PUT |
Send the following <languages> body with PUT:
| Body field | Value |
|---|---|
language | one element per supported language — a valid RFC 5646 tag (e.g. en-GB, da-DK) |
curl
GET:
Code
PUT:
Code
Example
Checking the current languages, then setting English and Danish as the supported languages:
Code
Code
Code
Code
Response
GET returns Code: 200 OK
Code
PUT returns Code: 200 OK
Code
Step 3: Set up forwarding
This step is optional. Forwarded messages are a separate set of notifications, with their own templates, that Keepit sends only to partner users (tokens) — for example, to keep a partner informed about events on their customer accounts. They are distinct from the messages the customer receives, and the two are controlled independently: enabling or disabling one does not affect the other. Follow this step only if you need partner users (tokens) to receive them.
Set forwarding up in order: first enable it at the partner level, then choose which message types to forward, then configure which users (tokens) receive them. Everything in this step is configured on whichever partner account you want to receive the forwarded messages — that partner account doesn't have to be the direct parent of the accounts being forwarded from; it can sit several levels up the hierarchy.
You can only turn forwarded messages on or off — their content can't be edited (unlike customer messages, which you fully customize in Step 1).
Enable forwarding at partner level
See the Get account forwarding recipient and Set account forwarding recipient pages for details.
Check whether forwarding is currently on for the partner account, then switch it on or off. This is the master switch — users (tokens) will not receive forwarded messages until it is enabled.
| Method | GET / PUT |
| Endpoint | /users/{partnerId}/forwarded_messages/recipient/ |
| Body | none for GET; XML <recipient> for PUT |
Send the following <recipient> body with PUT:
| Body field | Value |
|---|---|
enabled | true to enable forwarding for the partner, false to disable |
curl
GET:
Code
PUT:
Code
Example
Checking forwarding status, then enabling it for the partner account:
Code
Code
Code
Code
Response
GET returns Code: 200 OK
Code
PUT returns Code: 200 OK
Code
Choose which messages to forward
First, list the available forwarded message types and their current enabled status.
See the List forwarded messages page for details.
| Method | GET |
| Endpoint | /users/{partnerId}/forwarded_messages |
| Body | none |
curl
Code
Example
Listing all available forwarded messages:
Code
Response
Code: 200 OK
Code
Then enable or disable a message type as needed.
See the Update forwarded message page for details.
| Method | PUT |
| Endpoint | /users/{partnerId}/forwarded_messages/{name} |
| Body | XML <message> |
Send the following <message> body:
| Body field | Value |
|---|---|
enabled | true or false |
curl
Code
Example
Enabling the restore-started forwarded message:
Code
Code
Response
Code: 200 OK
Code
These 15 message types have a forwarded template and are delivered when enabled, grouped here as they appear in the portal UI:
- Connectors —
device-added,device-health-changed,multigeo-config-changed - Backups —
first-backup-complete,backup-failed,backup-incomplete - Data Recovery —
restore-started,restore-succeeded,restore-failed,restore-incomplete - Seat Limits —
approaching-seats-quota,auto-add-stopped,seats-quota-violated,resource-gracetime-expires,resource-gracetime-expired
Configure user (token) recipients
Independent of the master switch above, each user (token) also has its own recipient status. Use these two endpoints to check a user (token)'s current status and toggle it — excluding a user (token) entirely, or excluding one specific customer account from a user (token) that's otherwise on. The excluded customer account doesn't need to be a direct child of the partner account — it can sit several levels below.
The user (token) GUID is the <guid> value from the List tokens endpoint (GET /users/{accountId}/tokens), using the Accept: application/vnd.keepit.v1+xml (or v2) header.
Whether a user (token) receives forwards at all:
See the Get token forwarding recipient and Set token forwarding recipient pages for details.
| Method | GET / PUT |
| Endpoint | /users/{partnerId}/forwarded_messages/recipient/tokens/{tokenId} |
| Body | none for GET; XML <recipient> for PUT |
Send the following <recipient> body with PUT:
| Body field | Value |
|---|---|
enabled | true so the user (token) receives forwards for everything it has access to, or false to exclude it entirely |
curl
GET:
Code
PUT:
Code
Example
Checking a user (token)'s status, then excluding it entirely:
Code
Code
Code
Code
Response
GET returns Code: 200 OK
Code
PUT returns Code: 200 OK
Code
Set enabled back to true to undo the exclusion.
Whether a user (token) receives forwards about one specific customer account:
See the Get token recipient for a customer account and Set token recipient for a customer account pages for details.
| Method | GET / PUT |
| Endpoint | /users/{partnerId}/forwarded_messages/recipient/tokens/{tokenId}/targets/{customerAccountId} |
| Body | none for GET; XML <recipient> for PUT |
Send the following <recipient> body with PUT:
| Body field | Value |
|---|---|
enabled | true (the default) so this customer account reaches the user (token) like any other, or false to exclude just this one |
curl
GET:
Code
PUT:
Code
Example
Checking the status for one customer account, then excluding it from an otherwise-on user (token):
Code
Code
Code
Code
Response
GET returns Code: 200 OK
Code
PUT returns Code: 200 OK
Code
Set enabled back to true to undo the exclusion.
Step 4: Work with the in-app mailbox
Every user account has an in-app mailbox where Keepit delivers notifications. Use these calls to list, read, and delete messages.
A message — including a forwarded one — is delivered two ways at once: as an email to the user (token)'s aname (its login), and as an entry in that user (token)'s in-app mailbox here. If a user (token)'s aname is a real address, that address gets the emails too, so choose recipient users (tokens) deliberately. Checking the mailbox is the quickest way to confirm delivery without waiting on email.
List messages
See the List mailbox messages page for details.
Returns all non-deleted messages for an account's user (token), sorted from latest to earliest. You must authenticate with a user (token) belonging to the same account — a user (token) from elsewhere can't read it.
The user (token) GUID is the <guid> value from the List tokens endpoint (GET /users/{accountId}/tokens), using the Accept: application/vnd.keepit.v1+xml (or v2) header.
| Method | GET |
| Endpoint | /bl/mailbox/{accountId}/tokens/{tokenId} |
| Body | none |
Pagination is supported. Use the limit parameter to cap the number of messages returned and offset to page through them, e.g. ?limit=20&offset=20 for the second page of 20. The <read> element is only present on messages that have already been opened; it is absent for unread messages.
curl
Code
Example
Listing messages for an account:
Code
Response
Code: 200 OK
Code
Read a message
See the Read mailbox message page for details.
Returns the HTML content of a specific message. The response is a text/html document suitable for rendering directly in an iframe. Retrieving a message this way marks it as read if it was not already.
| Method | GET |
| Endpoint | /bl/mailbox/{accountId}/{mailId} |
| Body | none |
curl
Code
Example
Reading a specific message:
Code
Response
Code: 200 OK
Code
Delete a message
See the Delete mailbox message page for details.
Marks the specified message as deleted. Deleted messages are no longer returned by the list endpoint.
| Method | DELETE |
| Endpoint | /bl/mailbox/{accountId}/{mailId} |
| Body | none |
curl
Code
Example
Deleting a message from the mailbox:
Code
Response
Code: 200 OK
Code