---
url: https://talkjs.com/docs/Features/Notifications/Email_Notifications/
title: "Email notifications | TalkJS Docs"
---

For AI agents: Find a documentation index at https://talkjs.com/llms.txt (full content at https://talkjs.com/llms-full.txt). Get a markdown version of any page by appending .md to its URL path.

# Email notifications

Send and customize email notifications for offline users.

When a user is offline for a while, you can send email notifications for any messages they missed.

TalkJS automatically handles sending email notifications to users who go offline. You can set a custom sender address, adjust when emails are sent, and who receives them, all from your [dashboard](https://talkjs.com/dashboard).

If you're on the Growth plan or higher, you can fully customize the look and feel of your notification emails with [email themes](https://talkjs.com/docs/Features/Notifications/Email_Notifications/Themes/).

![Example email notification. The notification shows messages that the user may have missed while they were offline, and a link to click and join the chat.](https://talkjs.com/docs/example-email-notification.png)

Example notification email

## Enable email notifications

You can globally enable email notifications from the **Notifications** page of your dashboard, in the **Email settings** section, using the **Enable email** toggle.

Once enabled, any user with at least one valid email address on record automatically starts receiving notifications after being offline for a while. Users can have more than one email address, and TalkJS notifies all email addresses on record.

## Set up custom domain

You can optionally set up a custom domain for email notification purposes, for example `chat.example.com` or `notificationsdomain.com`. Using a custom domain can improve deliverability, and prevent conflicts if your main domain already has its own mail server.

To set up a custom domain, you must have access to your domain's DNS configuration to add the necessary records.

Steps to set it up:

1.  On your [TalkJS dashboard](https://talkjs.com/dashboard/), from the top right menu, select **Email domains**.
2.  Add your domain in the section **Add domain**.
3.  Find your domain in the list and select **Details**.
4.  To verify your domain, copy the relevant records and add them to your DNS settings. `TXT` and `CNAME` records must be verified to use a custom domain. An `MX` record is required to use the [reply by email](https://talkjs.com/docs/Features/Notifications/Email_Notifications/#reply-by-email) feature.
5.  Refresh your TalkJS dashboard page. Your domain should now show up as verified.

You can add multiple dedicated domains, but only one can be active at any point in time.

## Set up custom sender address

By default all email notifications come from the address `notifications@r.talkjs.com`. If you’re using a custom email domain, you can customize the local part of the sender address (the part before the @-symbol) directly from your TalkJS dashboard.

To customize your sender address:

1.  On your [TalkJS dashboard](https://talkjs.com/dashboard/), from the top right menu, select **Email domains**.
2.  From the list of domains, find the email domain for which you'd like to change the local part, and select **Details**.
3.  On the details page, under **Sender addresses**, update the email details and select **Save sender addresses**.

Your email notifications are now sent from the custom sender address you specified.

If the details page doesn't show any settings for the local part, and your notification emails come from an address with a long, random-looking sender name, then custom sender addresses likely aren't enabled for your account. Get in touch and a member of the TalkJS team can get this set up for you.

## Set notification timeout

TalkJS groups missed messages into a single email notification and sends it after a defined period of user inactivity. In the **Timeout (in seconds)** field, you can specify the period of inactivity after which TalkJS should send a notification. The maximum allowed timeout is 900 seconds (15 minutes).

## Configure message inclusion

You can control whether any missed messages themselves are included in the body of the email notifications. Use the **Include unread messages in the email notification** checkbox to turn message inclusion on or off.

## Configure attachments

You control whether any chat message attachments are included in email notifications.

On the **Notifications** page, choose your preference from the **Email attachments** selection, with the following options:

-   **Enabled**: All attachments are included in notifications.
-   **Enabled (excluding images)**: Only attachments other than image files are included in notifications.
-   **Disabled**: No attachments are included in notifications.

## Personalize content with macros

Beyond delivery settings, you can also customize the content of your notification emails.

You can use a limited macro syntax to personalize your email notifications, for example `Hello {{recipient.name}}!`.

You can use macros directly in various fields on the **Notifications** page of your TalkJS dashboard.

You can also pass your metadata for users or conversations using the macro syntax. For example, you can specify a custom special token `{{sender.custom.specialToken}}`. The `custom` field has to be an object with strings as values.

For example, you can specify a special token for Alice in your code:

```javascript
session.currentUser.set({ custom: { specialToken: 'jd71ba91n' } });
```

Note that custom user data is publicly visible (for example, in the browser), so don't use this for sensitive data.

Similarly, you can customize a [conversation](https://talkjs.com/docs/JavaScript_Data_API/Conversations/):

```javascript
const conversation = session.conversation('order_83562938');
conversation.set({
  subject: 'Hair Wax 5 Gallons',
  custom: {
    sellerId: 'seller_mq082jqid92',
  },
});
```

Fields that you can personalize with macros include:

-   Subject
-   Sender name
-   Unsubscribe link text
-   Header (inside the email body)
-   Inbox link text
-   Inbox URL
-   Footer

## Localize notification content

You can localize the content of email notifications using app metadata [custom fields](https://talkjs.com/docs/UI_Components/Email_Component/#app), which support localization.

To localize content with app custom fields:

1.  On the **Settings** page of your TalkJS dashboard, in the **App metadata** section, add a custom field for the string you want to localize. For example: `newMessagesText`.
2.  For each locale you want to support, add another custom field with the same, plus a `:` colon and locale suffix to the field name. For example, add `newMessagesText:fr` for French or `newMessagesText:zh-TW` for Chinese as spoken in Taiwan.

```json
{
  "newMessagesText": "You have new messages",
  "newMessagesText:fr": "Vous avez de nouveaux messages",
  "newMessagesText:zh-TW": "你有新訊息"
}
```

3.  On the **Notifications** page of your dashboard, use the base custom field (without suffix) directly in your email notification header or [email theme](https://talkjs.com/docs/Features/Notifications/Email_Notifications/Themes/). For example, you could set the **Subject** field to: `{{app.custom.newMessagesText}}`.

That's it. TalkJS now automatically renders the custom field in the user's locale.

TalkJS resolves the field by trying, in order: the user's full locale, language code, your app's default locale, and as a fallback the unlocalized field.

## Link back to your app

You can link back to your site or app directly from your email notifications, so that users can easily rejoin the conversation. Add your link under **Inbox URL** on the **Notifications** page of your [TalkJS dashboard](https://talkjs.com/dashboard).

You can either add a plain link, for example `https://example.com`, or use [template macros](https://talkjs.com/docs/Features/Notifications/Email_Notifications/#personalize-content-with-macros) to let TalkJS build the inbox URL to go directly to the correct page or conversation.

The inbox URL applies globally to all users, unless overridden per user [role](https://talkjs.com/docs/Concepts/Roles/).

### Example: Link to inbox

If you're using the [Inbox prebuilt chat UI](https://talkjs.com/docs/Features/Chat_UIs/#inbox), you can make the inbox URL immediately preselect the right conversation. For example, if you have a user's inbox on `https://example.com/inbox` and their conversation ID is `123456`, you can add the conversation ID in a query parameter: `https://example.com/inbox?conversation=123456`. With a template macro, you could then add the following inbox URL:

```html
https://example.com/inbox?conversation={{conversation.id}}
```

This way, TalkJS generates a URL to preselect the correct conversation.

### Example: Link to product page

You can link straight to a page about a product or order, by adding a [custom field](https://talkjs.com/docs/Concepts/Conversations/#conversation-data) to the conversation to identify the product or order. For example, you could pass `{"productId": "12345"}` when creating the conversation, and then configure the inbox URL as follows:

```html
https://yoursite.com/orders/{{conversation.custom.productId}}
```

With a [chatbox](https://talkjs.com/docs/Features/Chat_UIs/#chatbox) or [pop-up](https://talkjs.com/docs/Features/Chat_UIs/#popup) embedded on the destination page, users can directly continue their conversation right there.

## Reply by email

Email replies let users stay engaged with conversations even when they’re not in your app.

When a user replies via email, their reply automatically shows up in the chat conversation. No additional setup is needed for replying by email, as TalkJS automatically routes replies to the correct conversation.

Users who only have `Read` [access](https://talkjs.com/docs/Concepts/Participants/#access) to a conversation can receive email notifications, but replies they send to a notification email won't show up in the conversation.

You can enable and turn off reply by email using the **Enable replying to email notifications via email** checkbox.

## Unsubscribe from emails

All email notifications include an unsubscribe link which, when clicked, unsubscribes the user. Including an unsubscribe link ensures reliable delivery, and complies with [Google's requirements for bulk email senders](https://support.google.com/a/answer/81126).

When a user unsubscribes from email notifications, they won't receive any further email notifications about unread messages. You won't be notified that a user has unsubscribed.

In case a user clicks the unsubscribe link by mistake, the link takes them to a page where they can resubscribe.

If you're on the [Growth plan](https://talkjs.com/pricing/) or higher, you can [customize the unsubscribe link](https://talkjs.com/docs/Features/Notifications/Email_Notifications/Themes/#customize-unsubscribe-link) with email themes.

## Manage or turn off email notifications

You can globally turn off email notifications from the **Notifications** page of your dashboard, in the **Email settings** section, by turning off **Enable email**.

To turn off email notifications for a specific user, you can remove the user's email address by setting their `email` field to `null`.

You can also use the [REST API](https://talkjs.com/docs/REST_API/Participation/#modify-participation) to modify or turn off notifications for a participant in a conversation. Specifically, each participant has a `notify` property, which can be set to:

-   `true`: Send the user notifications.
-   `"MentionsOnly"`: Only send the user notifications for messages in which they are @mentioned.
-   `false`: Don't send the user notifications.

When notifications are turned off, your user won't receive any notifications for that conversation, including email notifications.

## See also

-   [Email themes](https://talkjs.com/docs/Features/Notifications/Email_Notifications/Themes/)
-   [Email component](https://talkjs.com/docs/UI_Components/Email_Component/) reference details
-   [SMS notifications](https://talkjs.com/docs/Features/Notifications/SMS_Notifications/)
-   [Mobile push notifications](https://talkjs.com/docs/Features/Notifications/Mobile_Push_Notifications/)