Endpoints for the messages Keepit sends on a partner's behalf: the languages a partner supports, the message templates themselves, forwarding of customer notifications to partner tokens, and the in-app mailbox each account receives messages in.
See How to Set Up Messages and Notifications for a walkthrough of the whole setup.
Get supported languages
Returns the languages the partner supports in its message bundle. A message is only delivered in a language listed here, so this is the first thing to check when setting up messages.
This endpoint is only accessible by partner-type tokens. The {partnerId} must be
either the authenticated account or a child of it.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Get supported languages › Responses
Set supported languages
Sets the languages the partner supports in its message bundle.
The submitted list replaces the current one entirely. Include every language you want to keep active, not just the ones you are adding.
An account must have its own languages set before any message customized directly on it can be delivered. Customizing a message on an account with no languages of its own saves the template but never sends it. Accounts that only inherit their messages are unaffected — they use the parent's languages.
This endpoint is only accessible by partner-type tokens. The {partnerId} must be
either the authenticated account or a child of it.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Set supported languages › Responses
List messages
Returns every message available in the partner's message bundle, together with whether each one is enabled.
Response version selection follows the API versions rules. The v2
schema additionally reports each message's group, the account an inherited state
comes from, and the per-language templates.
In v0, a message with no enabled element is inherited from the parent account. In v2
this is explicit: the message carries either enabled (set on this account) or
inherited (identifying the account that set it).
This endpoint is only accessible by partner-type tokens. The {partnerId} must be
either the authenticated account or a child of it.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Headers
AcceptList messages › Responses
Get message content
Returns the error status and the template content of a single message in one language.
If the template is set directly on this account, the response contains a content
block only. If it is inherited, the response also contains an inherited element
identifying the account it comes from. When the requested language has no translation,
fallback names the language used in its place.
When no account in the chain has enabled or disabled the message, the response is an
empty message element.
This endpoint is only accessible by partner-type tokens. The {partnerId} must be
either the authenticated account or a child of it.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
messageNameTextual identifier of a message in the message bundle, such as welcome or forgotpass.
language[a-z]{2}(-[A-Z]{2})? · requiredLanguage tag per RFC 5646 / BCP 47 (e.g. en, en-US).
Get message content › Responses
Update message
Updates one message for the partner. The body determines what changes: send enabled
to enable or disable the message, send one or more update blocks to define its
template per language, or send both in a single request.
Omitting enabled restores inheritance — the message then follows whatever the parent
account has set.
The template fields accept inline markup as well as plain text. Substitution variables
such as <fullname/>, <resource-usage> and <resource-limit> are resolved against
the recipient when the message is generated. Preview the result with
Render message template before
storing it.
Customizing a template on an account requires that account to have its own languages set first, see Set supported languages. Otherwise the template is stored but never delivered.
Enabling or disabling a message here is independent of whether it is forwarded to partner tokens, which is configured through the forwarded messages endpoints.
This endpoint is only accessible by partner-type tokens. The {partnerId} must be
either the authenticated account or a child of it.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
messageNameTextual identifier of a message in the message bundle, such as welcome or forgotpass.
Update message › Responses
success
Render message template
Renders the supplied message template for a given account, resolving substitution
variables such as <fullname/> against that account. Use it to preview a template
before storing it with
Update message.
The response is an XHTML document that can be placed directly in an iframe. On a
parse or processing error the endpoint returns 400 with a plain text document
describing the problem.
Templates that use device-specific substitution variables also need device-guid in
the request body.
This endpoint is only accessible by partner-type tokens. The {partnerId} must be
either the authenticated account or a child of it.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
messageNameTextual identifier of a message in the message bundle, such as welcome or forgotpass.
Render message template › Responses
success
List forwarded messages
Returns every forwarded message available in the partner's message bundle, its group, and whether it is forwarded to the partner.
Forwarded messages are a separate notification set from the customer messages listed by List messages, with their own templates — not copies of what the customer receives. They keep the partner informed about events on its customer accounts.
enabled reflects the effective state — either set on this account or inherited from
above. When it is false, the message is not forwarded to the partner.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
List forwarded messages › Responses
Get forwarded message content
Returns the error status and the template content of a single forwarded message in one language.
If the template is inherited, the response also contains an inherited element
identifying the account it comes from. When the requested language has no translation,
fallback names the language used in its place.
When no account in the chain has enabled or disabled the message, the response is an
empty message element.
Forwarded message templates are configured on the root account and cannot be customized per partner, so this endpoint is read-only for content.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
messageNameTextual identifier of a message in the message bundle, such as welcome or forgotpass.
language[a-z]{2}(-[A-Z]{2})? · requiredLanguage tag per RFC 5646 / BCP 47 (e.g. en, en-US).
Get forwarded message content › Responses
Update forwarded message
Enables or disables a forwarded message for the partner, or restores inheritance from
the parent account by omitting enabled.
Unlike Update message, enabled here does not
switch on template customization. Template customization is not allowed by design — all
forwarded message templates are configured on the root account and are only changed by
a release or a database update.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
messageNameTextual identifier of a message in the message bundle, such as welcome or forgotpass.
Update forwarded message › Responses
success
Get account forwarding recipient
Returns whether the partner account receives forwarded messages. This is the account-wide switch: off, and nothing forwards for anyone, regardless of any token or customer-account setting below it.
Defaults to false.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Get account forwarding recipient › Responses
Set account forwarding recipient
Enables or disables forwarded messages for the partner account as a whole — every token on the account, for every customer account beneath it.
This is the account-wide switch: off, and nothing forwards for anyone, no matter what any individual token or customer-account setting says. When it's on, use Set token forwarding recipient to exclude a token entirely, or Set token recipient for a customer account to exclude one specific customer account from a token that otherwise receives for everything.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Set account forwarding recipient › Responses
Get token forwarding recipient
Returns whether one partner token receives forwarded messages about all of the customer accounts it has access to.
Defaults to true.
The response echoes the token the setting applies to in token-guid.
The {tokenId} is the guid value reported by
List tokens.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenId[a-z0-9]{6}-[a-z0-9]… · requiredAccess token identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Get token forwarding recipient › Responses
Set token forwarding recipient
Enables or disables one partner token as a recipient of forwarded messages about all of the customer accounts it has access to.
The response echoes the token the setting was applied to in token-guid.
The {tokenId} is the guid value reported by
List tokens.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenId[a-z0-9]{6}-[a-z0-9]… · requiredAccess token identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Set token forwarding recipient › Responses
Get token recipient for a customer account
Returns whether one partner token receives forwarded messages about one specific customer account.
Setting this to true has no effect — a token that's on already receives forwards
about every customer account it has access to; this endpoint only does something when
set to false, to exclude one specific customer account from it.
The response echoes the token and the customer account in token-guid and
target-account.
The {tokenId} is the guid value reported by
List tokens; {customerAccountId} is the account
the forwarded messages are about.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenId[a-z0-9]{6}-[a-z0-9]… · requiredAccess token identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
customerAccountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Get token recipient for a customer account › Responses
Set token recipient for a customer account
Excludes (or re-includes) one specific customer account from a partner token that otherwise receives forwarded messages about everything it has access to.
Only enabled=false has an effect. A token that's on already receives forwards about
every customer account it has access to, so enabled=true here does nothing — every
account is already included unless explicitly excluded.
The response echoes the token and the customer account the setting was applied to in
token-guid and target-account.
The {tokenId} is the guid value reported by
List tokens; {customerAccountId} is the account
the forwarded messages are about.
path Parameters
partnerId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenId[a-z0-9]{6}-[a-z0-9]… · requiredAccess token identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
customerAccountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Set token recipient for a customer account › Responses
List mailbox messages
Returns the non-deleted messages in the account's in-app mailbox, sorted by delivery time from latest to earliest.
Every user account has an in-app mailbox. Whenever Keepit contacts a user, the message is posted to this mailbox and optionally also sent by email.
The listing carries each message's subject and delivery time but not its body — fetch
that with Read mailbox message using the
guid from this response.
The {tokenId} is the guid value reported by
List tokens.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenId[a-z0-9]{6}-[a-z0-9]… · requiredAccess token identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
query Parameters
limitMaximum number of messages to return.
offsetPagination offset.
List mailbox messages › Responses
Mark all messages as read
Marks every message in the account's mailbox as read. Returns 200 and a plain text confirmation.
The request must carry a body, even though its content is ignored. Any well-formed XML
document is accepted — <read/> works. Sending an empty body returns 400 with an XML
parse error.
To mark a single message as read, fetch it with Read mailbox message — reading a message marks it read as a side effect.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenId[a-z0-9]{6}-[a-z0-9]… · requiredAccess token identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Mark all messages as read › Responses
success
Count mailbox messages
Returns the total number of messages in the account's mailbox.
Use limit when you only need to know whether the mailbox holds at least a given
number of messages — the count stops there instead of counting the whole mailbox.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenId[a-z0-9]{6}-[a-z0-9]… · requiredAccess token identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
query Parameters
limitCaps the number reported. When supplied, the response is the lesser of the actual message count and this value.
Count mailbox messages › Responses
Count unread mailbox messages
Returns the number of unread messages in the account's mailbox — the messages whose
read element is absent from
List mailbox messages.
Use limit when you only need to know whether the mailbox holds at least a given
number of unread messages.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
tokenId[a-z0-9]{6}-[a-z0-9]… · requiredAccess token identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
query Parameters
limitCaps the number reported. When supplied, the response is the lesser of the actual unread message count and this value.
Count unread mailbox messages › Responses
Read mailbox message
Returns the contents of one message as an XHTML document, with no XML envelope and no schema.
The response is a complete document rather than a fragment: it carries an XML
declaration, the XHTML namespace, and a head with the message subject as its title
and a link to the account theme's stylesheet. It can be placed directly in an iframe.
Reading a message marks it as read if it was not already. There is no way to fetch the body without changing its read state.
The message must belong to the mailbox of the authenticated token. A {mailId} that
exists on another token of the same account returns 404, not the message.
The {mailId} is the guid value reported by
List mailbox messages.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
mailId[a-z0-9]{6}-[a-z0-9]… · requiredIdentifier of a message in an in-app mailbox, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Read mailbox message › Responses
success
Delete mailbox message
Marks one message as deleted. Returns 200 on success. Deleted messages are no longer returned by List mailbox messages.
The {mailId} is the guid value reported by
List mailbox messages.
path Parameters
accountId[a-z0-9]{6}-[a-z0-9]… · requiredAccount identifier, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
mailId[a-z0-9]{6}-[a-z0-9]… · requiredIdentifier of a message in an in-app mailbox, in the form xxxxxx-xxxxxx-xxxxxx (lowercase letters and digits).
Delete mailbox message › Responses
success
List time zones
Returns the named time zones the back end supports.
The names follow the standard IANA time zone database, in Area/Location form. Query
this endpoint rather than relying on a copy of that database: it returns the list the
back end actually implements, so it is the authoritative answer.