Skip to main content

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 started#

To enable email integration, you must provide an emailOptions object to the constructor.

import CollabServer from '@pdftron/collab-server';
const server = new CollabServer({
...otherOptions,
emailOptions: {
emailHandler: () => {},
emailQueueTimer: 1000,
emailOnAnnotationCreated: true
}
})

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 emails#

For invites, the emailHandler will be called with the following parameters.

  • type (string) the type of email. Will be 'invite'
  • emailData (InviteEmailData) information about the event
  • context (Context) context about the user. See the context for more info.

Message emails#

For 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 event
  • context (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 integration#

To integrate with SendGrid, use the CollabServer.sendGridEmailHandler function as your emailHandler.

Please note you can still provide the emailQueueTimer and emailOnAnnotationCreated options.

import CollabServer from '@pdftron/collab-server';
import SendGrid from '@sendgrid/mail';
const server = new CollabServer({
...otherOptions,
emailOptions: {
emailHandler: CollabServer.sendGridEmailHandler({
sendGrid: SendGrid,
emailServiceApiKey: "your_sendgrid_api_key",
emailSender: "your_verified_email",
senderName: "name_of_sender",
templateId: {
message: "template_id_for_message_emails",
invite: "template_id_for_invite_emails"
},
getTemplateData: (type, data) => {
return {
subject: 'Your subject here',
custom: 'any other custom data'
}
}
}),
emailQueueTimer: 1000,
emailOnAnnotationCreated: true
}
})

CollabServer.sendGridEmailHandler(options)#

  • options (object) your sendgrid options
    • sendGrid (SendGrid) a reference to the @sendgrid/mail module.
    • emailServiceApiKey (string) your send grid API key
    • emailSender (string) your verified send grid sender email
    • senderName (string) the name of who is sending the email
    • templateId (object) your template IDs for emails
      • message (string) template ID for message emails
      • invite (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>

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:

<html>
<body>
<h1>{{ title }}</h1>
<p>{{ message }}</p>
</body>
</html>

Your getTemplateData could look something like this:

const server = new CollabServer({
...otherOptions,
emailOptions: {
emailHandler: CollabServer.sendGridEmailHandler({
...other,
getTemplateData: (type, data) => {
if(type === 'message') {
const { messages } = data;
return {
subject: 'New messages!',
title: 'You have unread messages',
message: `You have ${messages.length} new messages waiting`,
}
}
if(type === 'invite') {
return {
subject: "You have been invited to a document",
title: `You were invited to ${data.documentName} by ${data.sentBy}`,
message: 'View the document here'
}
}
}
}),
}
})

By default, the following data is pre-populated in the dynamic data:

For invites:

  • documentName
  • documentId
  • sentBy

For messages:

Types#

InviteEmailData#

InviteEmailData is an object with the following properties

  • sentBy (string) the username of the person who triggered the event
  • documentId (string) the id of the corresponding document
  • documentName (string) the name of the corresponding document
  • sendTo (string[]) a list of emails who should receive the notification
  • usersInvited (object[]) a list of all users who were invited
    • id (string) the user's id
    • userName (string) the user's username
    • email (string) the user's emails

MessageEmailData#

MessageEmaildata is an object with the following properties

  • sendTo (string) the email who should receive the notification
  • messages (Message[]) A list of all the messages the user received since the last time this was called. See below for the Message properties

Message

Each Message object contains the following properties.

  • annotationId (string) the ID of the annotation the message belongs to
  • messageText (string) the text of the message
  • documentName (string) the name of the document the message belongs to
  • documentId (string) the Id of the document the message belongs to
  • sentBy (string) the user who sent the message