Receive emails with Node
Tags: mailisk, email, testing, node
Published: 2022-11-01 18:02:09

You've probably found a dozen posts about sending emails with Node. But what about _receiving_ them?

## Why?

When would you want to receive emails instead of sending them? The most common use cases are for testing password resets and email flows. A common email flow is signing up, receiving a code and entering that code to signup.

## How?

We'll be using the [mailisk](https://github.com/mailisk-app/mailisk-node) library for receiving emails. This is a free email testing service which allows us to read emails. It works by creating a virtual email server that we can send emails to.

The email addreses look like this `<anything>@mynamespace.mailisk.net`. Where `mynamespace` is the name of your [namespace](https://docs.mailisk.com/#creating-a-namespace). An email sent to an address that ends in `@mynamespace.mailisk.net` can be read using the API.

## Setup

Install the library with

```shell
npm install mailisk
```

We'll interact with the API using the **client**, you can create one by passing your [API Key](https://docs.mailisk.com/#getting-your-api-key)

```js
const { MailiskClient } = require('mailisk')

const mailisk = new MailiskClient({ apiKey: 'YOUR_API_KEY' })
```

## Receiving Email

We can use the [searchInbox](https://github.com/mailisk-app/mailisk-node#searchinboxnamespace-params) function to receive emails. It only needs one parameter, our [namespace](https://docs.mailisk.com/#creating-a-namespace).

```js
const { MailiskClient } = require('mailisk')

const mailisk = new MailiskClient({ apiKey: 'YOUR_API_KEY' })

mailisk.searchInbox('mynamespace').then(console.log)
```

A note here is that, by default, this will only return the _latest_ emails - any emails received in the past 5 seconds. This can be changed by overriding the `from_timestamp` parameter. You can check the [docs](https://github.com/mailisk-app/mailisk-node#searchinboxnamespace-params) for more information.

With that in mind, let's change it so it gives us all the emails in the inbox, regardless of when they were received

```js
mailisk.searchInbox('mynamespace', { from_timestamp: 0 }).then(console.log)
```

In order to show this works we'll need to send an email. You can send one using your own email provider (e.g. Gmail). Any address that ends with your namespace will work, here let's simply send it to `john@mynamespace.mailisk.net`

After sending the email and executing the script, this is what we get in the console

```js
{
  total_count: 1,
  options: { limit: 10, offset: 0, from_timestamp: 0, wait: true },
  data: [
    {
      id: '1667305800547-9KJHqVLG5',
      from: { address: 'test@example.com', name: '' },
      to: [ { address: 'john@mynamespace.mailisk.net', name: '' } ],
      subject: 'This is a test',
      html: 'false',
      text: 'Something goes here',
      received_date: '2022-11-01T12:30:00.000Z',
      received_timestamp: 1667305800,
      expires_timestamp: 1667565000,
      spam_score: 0.1
    }
  ]
}
```

### Sending emails

To make testing a bit easier we can also use mailisk to _send_ emails. These can only be sent to mailisk namespaces though

```js
...
const namespace = 'mynamespace'

await mailisk.sendVirtualEmail(namespace, {
  from: 'test@example.com',
  to: `john@${namespace}.mailisk.net`,
  subject: 'Testing',
  text: 'This is a test.',
})
```

As an example, let's send ourselves an email and then read it

```js
const { MailiskClient } = require('mailisk')

const namespace = 'mynamespace'

// create client
const mailisk = new MailiskClient({ apiKey: 'YOUR_API_KEY' })

async function main() {
  // send email
  await mailisk.sendVirtualEmail(namespace, {
    from: 'test@example.com',
    to: `john@${namespace}.mailisk.net`,
    subject: 'Testing',
    text: 'This is a test.',
  })

  // receive latest email
  const { data: emails } = await mailisk.searchInbox(namespace, {
    to_addr_prefix: `john@${namespace}.mailisk.net`,
  })

  // print out the subjects of all the recieved emails
  for (const email of emails) {
    console.log(`Received email with subject '${email.subject}'`)
  }
}

main().then(() => console.log('Done'))
```

You'll notice we also used `to_addr_prefix` here. This let's us filter the emails we fetch by their destination address. In this example we sent an email to `john@...`, and therefore we only care about emails sent to `john@...`. If we didn't filter this we would also return other emails, such as ones sent to `somethingelse@...`

## Closing notes

This should be enough to get you up and started with receiving emails in Node.

If you're using Cypress take a look at our post on [Password reset with Cypress](https://dev.to/mailisk/password-reset-with-cypress-34bc), which features the mailisk cypress plugin (and an example repository). Otherwise there's additional information about options for fetching emails in the [documentation](https://docs.mailisk.com/guides/nodejs.html) and [API Reference](https://docs.mailisk.com/api-reference/)