Email notifications
The collab server ships with utilities for sending your users' email notifications when they get a new message and when they are invited to a new document.
We also provide a default SendGrid integration if you do not already have an email service setup.
#
Get startedTo enable email integration, you must provide an emailOptions object to the constructor.
emailOptions
contains 3 properties, documented below.
emailHandler(type, emailData, context): void
#
The emailHandler is used to actually send emails to your customers. It is provided with all the data you need to generate a nice looking email.
The parameters passed depend on the type of email being sent. Below is the documentation for both sets of parameters.
#
Invite emailsFor invites, the emailHandler
will be called with the following parameters.
type
(string) the type of email. Will be 'invite'emailData
(InviteEmailData) information about the eventcontext
(Context) context about the user. See the context for more info.
#
Message emailsFor new messages, the emailHandler
will be called with the following parameters.
type
(string) the type of email. Will be 'message'emailData
(MessageEmailData) information about the eventcontext
(Context) context about the user. See the context for more info.
emailQueueTimer: number
#
The minimum amount of time between email triggers, in ms.
For example, if you set it to 60000
(60 seconds), the emailHandler
can only get called maximum once every 60 seconds. This only applies to message emails.
Defaults to 10 minutes.
emailOnAnnotationCreated: boolean
#
If true, message notifications will be triggered when any annotation is created, even if there is no message content attached.
Defaults to false.
#
Default SendGrid integrationTo integrate with SendGrid, use the CollabServer.sendGridEmailHandler function as your emailHandler
.
Please note you can still provide the emailQueueTimer
and emailOnAnnotationCreated
options.
CollabServer.sendGridEmailHandler(options)
#
options
(object) your sendgrid optionssendGrid
(SendGrid) a reference to the@sendgrid/mail
module.emailServiceApiKey
(string) your send grid API keyemailSender
(string) your verified send grid sender emailsenderName
(string) the name of who is sending the emailtemplateId
(object) your template IDs for emailsmessage
(string) template ID for message emailsinvite
(string) template ID for invite emails
getTemplateData
(function) A function that gets data for the email. Data returned here will be used in your dynamic template. See below for more info.
getTemplateData
#
The getTemplateData
is used to get data about the email and inject it into your SendGrid template. This allows you to set custom message text, subject, etc. This function can be asynchronous.
getTemplateData(type, data): Object | Promise<Object>
type
(string) either 'invite' or 'message'data
(Object) depending on thetype
param, this will either be passed a InviteEmailData or a MessageEmailData
note
To use a dynamic subject, you need to set the subject
of your dynamic template to {{{subject}}}
. See this thread for more details.
For example, if your SendGrid template looked like this:
Your getTemplateData
could look something like this:
By default, the following data is pre-populated in the dynamic data:
For invites:
documentName
documentId
sentBy
For messages:
messages
(an array of MessageEmaildata)
#
Types#
InviteEmailDataInviteEmailData
is an object with the following properties
sentBy
(string) the username of the person who triggered the eventdocumentId
(string) the id of the corresponding documentdocumentName
(string) the name of the corresponding documentsendTo
(string[]) a list of emails who should receive the notificationusersInvited
(object[]) a list of all users who were invitedid
(string) the user's iduserName
(string) the user's usernameemail
(string) the user's emails
#
MessageEmailDataMessageEmaildata
is an object with the following properties
sendTo
(string) the email who should receive the notificationmessages
(Message[]) A list of all the messages the user received since the last time this was called. See below for theMessage
properties
Message
Each Message
object contains the following properties.
annotationId
(string) the ID of the annotation the message belongs tomessageText
(string) the text of the messagedocumentName
(string) the name of the document the message belongs todocumentId
(string) the Id of the document the message belongs tosentBy
(string) the user who sent the message