Skip to content

Messaging

Logged in users may send messages to other users that exist in the system. Currently only e-mail is supported as transport, but this functionality may be extended to an internal messaging mechanism in a future release.

E-mail

Messages can only be sent to e-mail addresses that are assigned to users in the system. A lookup of the recipient is performed before the message is sent. The from header is automatically set to the e-mail address configured in entrystore.smtp.email.from, whereas the reply-to header is set to the e-mail address of the sending user if the username is an e-mail address, and to entrystore.smtp.email.reply-to otherwise. The configured entrystore.smtp.email.bcc receives a copy of every message. See SMTP settings.

Contrary to how messages for signup, password reset, etc. are handled, the generic messaging mechanism is currently not based on server-side provided templates. This means that the client needs to provide the full message body if a nicely formatted message is to be sent. This may change in the future when other transports in addition to e-mail are implemented.

In 6.x the body is sanitized before it is sent: basic formatting, block elements, links, tables, hr, sub, sup, code, pre and blockquote are kept, and inline styles are limited to color, background-color, font-size, font-weight, font-style, text-align, text-decoration, margin and padding. Other elements, e.g. style, script or head, are removed. HTML is removed from the subject, and line breaks in the subject are replaced by spaces.

API

Endpoint

https://{base}/store/message

Parameters

The following mandatory parameters are supported in a JSON-based request body:

  • transport: Mode of transport, currently only email is supported.
  • to: Username (e-mail address) of recipient, must be assigned to an existing user in the system. In 6.x it must be exactly one address (no list).
  • subject: The message subject (at most 200 characters in 6.x).
  • body: The message body. May contain HTML (at most 50000 characters in 6.x).

Example

POST https://{base}/store/message
Content-Type: application/json

{
  "transport": "email",
  "to": "user@in.system",
  "subject": "This is a test message",
  "body": "This is the body of the test message"
}

Response

Status Reason
200 The message has been sent
400 Missing or invalid parameters, or subject or body empty after sanitization
401 The request is not authenticated
403 The recipient does not exist
429 The rate limit has been exceeded (6.x)
503 The message could not be sent (6.x)

Rate limiting (6.x)

The number of messages per user is limited:

entrystore.message.rate.limit.max=10
entrystore.message.rate.limit.window=1h

The values above are the defaults; 0 disables the limit.

EntryStore 5.x

5.x does not sanitize the message, has no rate limit and no length limits, and answers 200 even if the message could not be sent.