Email Functions

Use the Email adapter to send email to simulation admins and participants from your application code.

Importing the adapter

To use the functions of the Email adapter, import it as shown:

import { emailAdapter } from 'epicenter-libs';

The emailAdapter namespace exports functions that make calls to the Email API.

learn more

For descriptions of the objects used by the Email adapter functions, read Email entities.

---

Email a participant

Use this function to allow a participant or facilitator to send an email to another user within a group.

note

There are two options for the sender/reply-to address:

1. The sender is identified as "System". This method is available to participants.
2. The sender is identified as a specific user. Requires REVIEWER-level authentication. To use this method, pass the following parameters:
   • optionals.from: The email address from which the message will appear to have been sent from.
   • optionals.replyTo: The email address that will be replied to by the recipient.
   • optionals.fromUserKey: The user key of the sender user. Overrides optionals.from.

Permissions

The role required for this function depends on the endpoint variant used:

• /email/user/{groupKey}/{userKey} → PARTICIPANT
• /email/user/{groupKey}/{userKey}/from/{from} → REVIEWER
• /email/user/{groupKey}/{userKey}/from/{from}/{replyTo} → REVIEWER
• /email/user/{groupKey}/{userKey}/as/{fromUserKey} → REVIEWER

Function description

The sendEmail() function:

• Constructs a POST request to one of the email endpoints listed above depending on sender options.
• Sends an email to the address associated with the target user.
• Supports plain text or HTML bodies.
• Supports attachments via the Attachment interface.
• Returns void to indicate a successful request.

Function signature

export async function sendEmail(
    groupKey: string,
    userKey: string,
    subject: string,
    emailBody: string,
    optionals: {
        familyNameFirst?: string;
        html?: boolean;
        from?: string;
        replyTo?: string;
        fromUserKey?: string;
        attachments?: Attachment[];
    } & RoutingOptions = {},
): Promise<void>

Parameters

• groupKey (string): The group key for the group the target user is a part of.
• userKey (string): The unique key identifying the recipient user.
• subject (string): The subject line.
• emailBody (string): The content of the email body.
• optionals (object, optional): Additional email and routing options:
  • familyNameFirst (string, optional): If true, formats the recipient’s family name before the given name. Defaults to false.
  • html (boolean, optional): If true, treats the email body as HTML. Defaults to false.
  • from (string, optional): Provide a custom sender email address here. However, if fromUserKey is provided, this is ignored.
  • replyTo (string, optional): Reply-to address. Can only be used in tandem with from.
  • fromUserKey (string, optional): Sends the email as if from the specified user.
  • attachments (Attachment[]): Array of attachments.
  • Also accepts RoutingOptions.

Return value

A promise that resolves to void, indicating the email was sent successfully.

Usage example

import { emailAdapter, authAdapter } from 'epicenter-libs';

// Sends an email with a smiley face PNG attachment
const groupKey = authAdapter.getLocalSession().groupKey;
const subject = 'check out this drawing!';
const emailBody = 'I hope you enjoy this smiley face!';
const attachments = [{
    encoding: 'BASE_64',
    name: 'testPic',
    contentType: 'image/png',
    data: 'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAAAIxJREFUWEdjZBhgwDjA9jMQ5YAvzmb/efaewquWGDXYPDvqgNEQGA2B0RAYGiFAy+KaqBAYdcDICgFQtQryMaHql1qhgjURklu3IzuKWDNwOoCSUCAlFHFmQ2J9gB4VpFgO0kvVZhaplhPlAJgPCSVKciwn6ACY5TDD8aV8Qg7EpXe0KB4NgdEQGA0BAF7VgCFTeobfAAAAAElFTkSuQmCC',
}];

// Sender appears as "System"
await emailAdapter.sendEmail(
  groupKey,
  '000001796733eef0842f4d6d960997018d9h',
  subject,
  emailBody,
  { attachments }
);

// Sender appears as provided "from" address
await emailAdapter.sendEmail(
  groupKey,
  '000001796733eef0842f4d6d960997018d9h',
  subject,
  emailBody,
  { attachments, from: 'sender@test.com' }
);

// Sender appears as "from", reply-to is different
await emailAdapter.sendEmail(
  groupKey,
  '000001796733eef0842f4d6d960997018d9h',
  subject,
  emailBody,
  { attachments, from: 'sender@test.com', replyTo: 'receiver@test.com' }
);

// Sender appears as the user associated with fromUserKey
await emailAdapter.sendEmail(
  groupKey,
  '000001796733eef0842f4d6d960997018d9h',
  subject,
  emailBody,
  { attachments, fromUserKey: '000001796733eef0842f4d6d960997018a33' }
);

---

Email an admin

Use this function to allow an admin to send an email to another admin.

note

Requires support-level authentication.

Permissions

Requires a role of SUPPORT or higher.

Function description

The sendEmailToAdmin() function:

• Constructs a POST request to /email/admin/{ADMIN_KEY}.
• Supports plain text or HTML bodies.
• Supports attachments via the Attachment interface.
• Returns void to indicate a successful request.

Function signature

export async function sendEmailToAdmin(
    adminKey: string,
    subject: string,
    emailBody: string,
    optionals: {
        familyNameFirst?: string;
        html?: boolean;
        attachments?: Attachment[];
    } & RoutingOptions = {},
): Promise<void>

Parameters

• adminKey (string): The unique key identifying the target admin.
• subject (string): The subject line.
• emailBody (string): The content of the email body.
• optionals (object, optional): Additional email and routing options:
  • familyNameFirst (string, optional): If true, formats the recipient’s family name before the given name. Defaults to false.
  • html (boolean, optional): If true, treats the email body as HTML. Defaults to false.
  • body (string, optional): Alternate content body of the email.
  • attachments (Attachment[]): Array of attachments.
  • Also accepts RoutingOptions.

Return value

A promise that resolves to void, indicating the email was sent successfully.

Usage example

import { emailAdapter } from 'epicenter-libs';

const adminKey = '000001796733eef0842f4d6d960997018d9h';
const subject = "Important update";
const body = "Please review the attached document.";

const attachment = {
    encoding: 'BASE_64',
    name: 'update.pdf',
    contentType: 'application/pdf',
    data: 'JVBERi0xLjQKJcfs...'
};

// Send email with attachment
await emailAdapter.sendEmailToAdmin(adminKey, subject, body, {
    attachments: attachment
});

// Send email with HTML formatting
await emailAdapter.sendEmailToAdmin(adminKey, subject, body, {
    html: true,
    attachments: attachment
});

---

Email support

To allow a user to send an email directly to the Epicenter support team, use the sendEmailToSupport() function.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

• Constructs a POST request to the endpoint /email/to/support.
• Supports attachments via the Attachment interface.
• Returns void upon successful submission.

export async function sendEmailToSupport(
    subject: string,
    emailBody: string,
    optionals: {
        supportType?: string;
        familyNameFirst?: string;
        html?: boolean;
        attachments?: Attachment[];
    } & RoutingOptions = {},
): Promise<void>

Parameters

• subject (string): The subject line for the email message.
• emailBody (string): The email body.
• optionals (object, optional): Additional configuration and routing options.
  • supportType (string, optional): Indicates the type of the support request (for example, "technical" or "billing").
  • familyNameFirst (string, optional): If true, formats the recipient’s family name before the given name. Defaults to false.
  • html (boolean, optional): If true, treats the email body as HTML. Defaults to false.
  • attachments (Attachment[]): Array of attachments.
  • Also accepts RoutingOptions to control network routing.

Return value

A promise that resolves to void, indicating the email was sent successfully.

Usage example

import { emailAdapter } from 'epicenter-libs';

const subject = "Project not loading correctly";
const body = "Hi Support, I'm having trouble loading my project. Can you help?";

const attachments = [{
    encoding: 'BASE_64',
    name: 'error-log.txt',
    contentType: 'text/plain',
    data: 'U29tZSBsb2cgZGF0YSBoZXJlLi4u', // base64-encoded data
}];

// Send a plain text support email
await emailAdapter.sendEmailToSupport(subject, body);

// Send an HTML email with attachment and custom support type
await emailAdapter.sendEmailToSupport(subject, body, {
    html: true,
    supportType: 'technical',
    attachments,
});

---