@liveblocks/emails
provides a set of functions that simplifies sending styled
emails with Notifications and
webhooks. This library is only intended for use in
your Node.js back end.
@liveblocks/emails
requires the
@liveblocks/node
package to be
installed and for react
to be a peer dependency in your
project.
This package exposes functions that enable easy creation of styled emails with React and HTML. Each method is designed to be used with our webhooks which means you must set them up first. Webhooks require an API endpoint in your application, and this is typically what they will look like.
We’ll only show the highlighted part below, as it’s assumed you’ve set this
already, and your file contains liveblocks
and event
.
We have two guides that take you through every step of setting up your email notifications, including setting up webhooks:
We have a number of examples that show you how to set up emails with your Comments or Text Editor application. Each Resend example has full ready-made email templates inside, which are a great starting point for your application.
These functions help you create emails to notify users of unread comments in threads. They fetch each relevant comment, filtering out any that have already been read, and help you style each comment’s body with either React or HTML.
The function also helps you distinguish between unread mentions and unread replies.
A thread has unread replies if a comment was created after the readAt
date
on the notification, and created before or at the same time as the notifiedAt
date. All unread replies are returned in an array.
A thread has an unread mention if it has unread replies, and one of the replies mentions the user. A single comment with the latest mention is returned.
Takes a
thread notification webhook event
and returns unread comment body(s) related to the notification, as React nodes.
It can return one of three formats, an unreadMention
type containing one
comment, an unreadReplies
type returning multiple comments, or null
if there
are no unread mentions/replies. You can also
resolve user & room data
and
customize the components.
It’s designed to be used in a webhook event, which requires a
Liveblocks
Node.js
client and a
WebhookHandler
. Check
for the correct webhook event using
isThreadNotificationEvent
before running the function, such as in this Next.js route handler.
Similarly to on the client, you can resolve users and room info, making it easier to render your emails. For example, you can resolve a user’s ID into their name, and show their name in the email.
Each React component in the comment body can be replaced with a custom React
component, if you wish to apply different styles. Five components are available:
Container
, Paragraph
, Text
, Link
, Mention
.
Takes a
thread notification webhook event
and returns unread comment body(s) related to the notification, as an HTML-safe
string. It can return one of three formats, an unreadMention
type containing
one comment, an unreadReplies
type returning multiple comments, or null
if
there are no unread mentions/replies. You can also
resolve user & room data
and
customize the styles.
It’s designed to be used in a webhook event, which requires a
Liveblocks
Node.js
client, a
WebhookHandler
. Check
for the correct webhook event using
isThreadNotificationEvent
before running the function, such as in this Next.js route handler.
Similarly to on the client, you can resolve users and room info, making it easier to render your emails. For example, you can resolve a user’s ID into their name, and show their name in the email.
Each element in the comment body can be styled with custom CSS properties, if
you would like to change the appearance. Five elements are available:
paragraph
, code
, strong
, mention
, link
.
These functions help you create emails to notify users when they have an unread mention in a Text Editor document. In this case, a mention is not related to comments, but is instead an inline mention inside the text editor itself. If the mention has not been read, the functions fetch a text mention and its surrounding text, giving you more context, and helping you style the mention content with either React or HTML.
The functions helps to determine if the mention still exists in the document and will indicate that there’s no email to send in this case. Currently, only mentions in paragraph blocks create notifications, as there are limitations around retrieving mentions in plugins.
Before you get started, there are some limitations with text mentions that you should be aware of.
If a user is mentioned in a plugin or extension, a text mention notification is not sent. This is because Liveblocks doesn’t know the exact schema of your editor and all its plugins, and we can’t extract the data correctly. This means that only mentions in paragraph blocks are sent, and mentions in lists, checkboxes, etc., are not, as they are all powered by plugins. We’re investigating solutions for this, and we’d like to hear from you if you have any thoughts.
Tiptap optionally allows you to render multiple editors per page, instead of just one. For now, these functions only support one editor per room, but we’ll be looking to add support for more later.
Takes a
text mention notification webhook event
and returns an unread text mention with its surrounding text as React nodes. It
can also return null
if the text mention does not exist anymore or has been
already been read. You can also
resolve user & room data
and
customize the components.
It’s designed to be used in a webhook event, which requires a
Liveblocks
Node.js
client and a
WebhookHandler
. Check
for the correct webhook event using
isTextMentionNotificationEvent
before running the function, such as in this Next.js route handler.
Similarly to on the client, you can resolve users and room info, making it easier to render your emails. For example, you can resolve a user’s ID into their name, and show their name in the email.
Each React component in the mention context can be replaced with a custom React
component, if you wish to apply different styles. Three components are
available: Container
, Text
, and Mention
.
Takes a
text mention notification webhook event
and returns an unread text mention with its surrounding text as an HTML string.
It can also return null
if the text mention does not exist anymore or has been
already been read. You can also
resolve user & room data
and
customize the styles.
It’s designed to be used in a webhook event, which requires a
Liveblocks
Node.js
client and a
WebhookHandler
. Check
for the correct webhook event using
isTextMentionNotificationEvent
before running the function, such as in this Next.js route handler.
Similarly to on the client, you can resolve users and room info, making it easier to render your emails. For example, you can resolve a user’s ID into their name, and show their name in the email.
Each element in the comment body can be styled with custom CSS properties, if
you would like to change the appearance. Five elements are available:
paragraph
, code
, strong
, mention
, and link
.
We use cookies to collect data to improve your experience on our site. Read our Privacy Policy to learn more.