Sending and receiving emails

Momentic supports sending and receiving emails to and from specially allocated @usemomentic.com addresses. This feature is useful for testing email-based authentication (e.g OTPs), notifications, and other features that require opening emails.

​

Usage

Email functionality is currently surfaced through the JavaScript step. Within Momentic’s JavaScript sandbox, your code can access a special email object. This object contains the following utility functions:

​

Sending emails

The send utility function allows you to send an email to an inbox. The inbox provided in the from argument must be issued and authorized by Momentic.

• Function Signature
• Example

  async function send(params: {
    subject: string;
    body: string;
    to: string;
    from: string;
  }): Promise<void>;

​

Fetching the latest email

The fetchLatest utility function retrieves the most recent email received in your inbox. Optionally, you can filter for emails sent after a particular date. This can be useful for ensuring that you are not reading stale emails that were received before the test began.

This function will automatically retry until a matching email is found or the timeout is exhausted (if the timeout parameter is omitted, the default is 10 seconds). If no email is received within the timeout, an error is thrown.

If an email is received, the text content of the email will be available in the text field of the result. When trimWhitespace is true, which is the default behavior, adjacent whitespace characters will be combined to make the text easier to read and parse in future steps. If the email contains HTML content, the raw HTML will be provided in the html field.

• Function Signature
• Example

async function fetchLatest(params: {
  inbox: string, // inbox name allocated by momentic
  afterDate?: Date,
  timeout?: number,
  trimWhitespace: boolean = true,
}): Promise<Email>;

type Email = {
  subject: string; // subject line
  from: string; // sender's name and email
  fromEmail: string; // sender's email address
  to: string; // recipient's name and email address (the @usemomentic.com address allocated to your organization)
  time: number; // unix timestamp for when the email was received
  secondsAgo: number; // how many seconds ago the email was received
  size: number | undefined; // size of the email in bytes

  text: string; // the text content of the email. if trimWhitespace is true, adjacent whitespace characters will be combined
  html: string | undefined; // if the email has HTML content, this field will contain the raw HTML
};

​

Fetching all recent emails

The fetchAll utility function retrieves all recently received emails in your inbox. You can filter for emails received after a certain date and set a limit on the number of emails returned. By default, these parameters are set to 15 minutes ago and 3 emails; the maximum allowed values are 24 hours and 10 emails.

This function runs instantaneously and does not retry or poll until an email exists. As such, it is the responsibility of the caller to ensure that the email they are interested in is already delivered by the time this function is invoked. If no emails exist in the inbox, the function will throw an error.

For more information on the format of each email and available formatting options, see the fetch latest email section.

• Function Signature
• Example

async function fetchAll(params: {
  inbox: string, // inbox name allocated by momentic
  afterDate?: Date,
  limit?: number,
  trimWhitespace: boolean = true,
}): Promise<Email[]>;

​

Creating isolated inboxes

Once you are allocated unique username from Momentic, you can create unlimited, isolated inboxes accessible from your organization by appending a suffix to the username. For example, if your unique username is momentic, you can also send emails to momentic+test@usemomentic.com and fetch results using the momentic+test inbox name.

We recommend using this strategy with a randomized suffix such as Date.now() when running multiple tests in parallel that require email access to prevent race conditions.