mailhog

A NodeJS library to interact with the MailHog API.

Contents

• Installation
• Initialization
  • Description
  • Parameters
  • Returns
  • Example
• API
  • messages
    • Description
    • Parameters
    • Returns
    • Example
  • search
    • Description
    • Parameters
    • Returns
    • Example
  • latestFrom
    • Description
    • Parameters
    • Returns
    • Example
  • latestTo
    • Description
    • Parameters
    • Returns
    • Example
  • latestContaining
    • Description
    • Parameters
    • Returns
    • Example
  • releaseMessage
    • Description
    • Parameters
    • Returns
    • Example
  • deleteMessage
    • Description
    • Parameters
    • Returns
    • Example
  • deleteAll
    • Description
    • Parameters
    • Returns
    • Example
  • encode
    • Description
    • Parameters
    • Returns
    • Example
  • decode
    • Description
    • Parameters
    • Returns
    • Example
• Testing
• License
• Author

Installation

npm install mailhog

Initialization

require('mailhog')(options) → Object

Description

The mailhog module returns an initialization function.
This function accepts an optional options object that is used for http.request calls to the MailHog API and returns the mailhog API object.

Parameters

| Name | Type | Required | Default | Description | | ---------------- | ------ | -------- | --------- | ------------------------ | | options.protocol | String | no | http: | API protocol | | options.host | String | no | localhost | API host | | options.port | Number | no | 8025 | API port | | options.auth | String | no | | API basic authentication | | options.basePath | String | no | /api | API base path |

Returns

Returns the mailhog API object with the following properties:

{
  options: Object,
  messages: Function,
  search: Function,
  latestFrom: Function,
  latestTo: Function,
  latestContaining: Function,
  releaseMessage: Function,
  deleteMessage: Function,
  deleteAll: Function,
  encode: Function,
  decode: Function
}

Example

const mailhog = require('mailhog')({
  host: 'mailhog'
})

mailhog.messages().then(result => console.log(result))

API

The following API descriptions assume that the mailhog API object has been initialized.

messages

mailhog.messages(start, limit) → Promise

Description

Retrieves a list of mail objects, sorted from latest to earliest.

Parameters

| Name | Type | Required | Default | Description | | ----- | ------ | -------- | ------- | --------------------------------- | | start | Number | no | 0 | defines the messages query offset | | limit | Number | no | 50 | defines the max number of results |

Returns

Returns a Promise that resolves with an Object.

The resolved result has the following properties:

{
  total: Number, // Number of results available
  count: Number, // Number of results returned
  start: Number, // Offset for the range of results returned
  items: Array   // List of mail object items
}

The individual mail object items have the following properties:

{
  ID: String,         // Mail ID
  text: String,       // Decoded mail text content
  html: String,       // Decoded mail HTML content
  subject: String,    // Decoded mail Subject header
  from: String,       // Decoded mail From header
  to: String,         // Decoded mail To header
  cc: String,         // Decoded mail Cc header
  bcc: String,        // Decoded mail Bcc header
  replyTo: String,    // Decoded mail Reply-To header
  date: Date,         // Mail Date header
  deliveryDate: Date, // Mail Delivery-Date header
  attachments: Array  // List of mail attachments
}

The individual attachments have the following properties:

{
  name: String,     // Filename
  type: String,     // Content-Type
  encoding: String, // Content-Transfer-Encoding
  Body: String      // Encoded content
}

Example

async function example() {
  // Retrieve the latest 10 messages:
  const result = await mailhog.messages(0, 10)

  // Log the details of each message to the console:
  for (let item of result.items) {
    console.log('From: ', item.from)
    console.log('To: ', item.to)
    console.log('Subject: ', item.subject)
    console.log('Content: ', item.text)
  }
}

search

mailhog.search(query, kind, start, limit) → Promise

Description

Retrieves a list of mail objects for the given query, sorted from latest to earliest.

Parameters

| Name | Type | Required | Default | Description | | ----- | ------ | -------- | ---------- | --------------------------------- | | query | String | yes | | search query | | kind | String | no | containing | query kind (from/to/containing) | | start | Number | no | 0 | defines the search query offset | | limit | Number | no | 50 | defines the max number of results |

Returns

Returns a Promise that resolves with an Object.

The resolved result has the following properties:

{
  total: Number, // Number of results available
  count: Number, // Number of results returned
  start: Number, // Offset for the range of results returned
  items: Array   // List of mail object items
}

The individual mail object items have the following properties:

{
  ID: String,         // Mail ID
  text: String,       // Decoded mail text content
  html: String,       // Decoded mail HTML content
  subject: String,    // Decoded mail Subject header
  from: String,       // Decoded mail From header
  to: String,         // Decoded mail To header
  cc: String,         // Decoded mail Cc header
  bcc: String,        // Decoded mail Bcc header
  replyTo: String,    // Decoded mail Reply-To header
  date: Date,         // Mail Date header
  deliveryDate: Date, // Mail Delivery-Date header
  attachments: Array  // List of mail attachments
}

The individual attachments have the following properties:

{
  name: String,     // Filename
  type: String,     // Content-Type
  encoding: String, // Content-Transfer-Encoding
  Body: String      // Encoded content
}

Example

async function example() {
  // Search the latest 10 messages containing "banana":
  const result = await mailhog.search('banana', 'containing', 0, 10)

  // Log the details of each message to the console:
  for (let item of result.items) {
    console.log('From: ', item.from)
    console.log('To: ', item.to)
    console.log('Subject: ', item.subject)
    console.log('Content: ', item.text)
  }
}

latestFrom

mailhog.latestFrom(query) → Promise

Description

Retrieves the latest mail object sent from the given address.

Parameters

| Name | Type | Required | Description | | ----- | ------ | -------- | ------------ | | query | String | yes | from address |

Returns

Returns a Promise that resolves with an Object.

The resolved mail object has the following properties:

{
  ID: String,         // Mail ID
  text: String,       // Decoded mail text content
  html: String,       // Decoded mail HTML content
  subject: String,    // Decoded mail Subject header
  from: String,       // Decoded mail From header
  to: String,         // Decoded mail To header
  cc: String,         // Decoded mail Cc header
  bcc: String,        // Decoded mail Bcc header
  replyTo: String,    // Decoded mail Reply-To header
  date: Date,         // Mail Date header
  deliveryDate: Date, // Mail Delivery-Date header
  attachments: Array  // List of mail attachments
}

The individual attachments have the following properties:

{
  name: String,     // Filename
  type: String,     // Content-Type
  encoding: String, // Content-Transfer-Encoding
  Body: String      // Encoded content
}

Example

async function example() {
  // Search the latest message from "[email protected]":
  const result = await mailhog.latestFrom('[email protected]')

  // Log the details of this message to the console:
  console.log('From: ', result.from)
  console.log('To: ', result.to)
  console.log('Subject: ', result.subject)
  console.log('Content: ', result.text)
}

latestTo

mailhog.latestTo(query) → Promise

Description

Retrieves the latest mail object sent to the given address.

Parameters

| Name | Type | Required | Description | | ----- | ------ | -------- | ----------- | | query | String | yes | to address |

Returns

Returns a Promise that resolves with an Object.

The resolved mail object has the following properties:

{
  ID: String,         // Mail ID
  text: String,       // Decoded mail text content
  html: String,       // Decoded mail HTML content
  subject: String,    // Decoded mail Subject header
  from: String,       // Decoded mail From header
  to: String,         // Decoded mail To header
  cc: String,         // Decoded mail Cc header
  bcc: String,        // Decoded mail Bcc header
  replyTo: String,    // Decoded mail Reply-To header
  date: Date,         // Mail Date header
  deliveryDate: Date, // Mail Delivery-Date header
  attachments: Array  // List of mail attachments
}

The individual attachments have the following properties:

{
  name: String,     // Filename
  type: String,     // Content-Type
  encoding: String, // Content-Transfer-Encoding
  Body: String      // Encoded content
}

Example

async function example() {
  // Search the latest message to "[email protected]":
  const result = await mailhog.latestTo('[email protected]')

  // Log the details of this message to the console:
  console.log('From: ', result.from)
  console.log('To: ', result.to)
  console.log('Subject: ', result.subject)
  console.log('Content: ', result.text)
}

latestContaining

mailhog.latestContaining(query) → Promise

Description

Retrieves the latest mail object containing the given query.

Parameters

| Name | Type | Required | Description | | ----- | ------ | -------- | ------------ | | query | String | yes | search query |

Returns

Returns a Promise that resolves with an Object.

The resolved mail object has the following properties:

{
  ID: String,         // Mail ID
  text: String,       // Decoded mail text content
  html: String,       // Decoded mail HTML content
  subject: String,    // Decoded mail Subject header
  from: String,       // Decoded mail From header
  to: String,         // Decoded mail To header
  cc: String,         // Decoded mail Cc header
  bcc: String,        // Decoded mail Bcc header
  replyTo: String,    // Decoded mail Reply-To header
  date: Date,         // Mail Date header
  deliveryDate: Date, // Mail Delivery-Date header
  attachments: Array  // List of mail attachments
}

The individual attachments have the following properties:

{
  name: String,     // Filename
  type: String,     // Content-Type
  encoding: String, // Content-Transfer-Encoding
  Body: String      // Encoded content
}

Example

async function example() {
  // Search the latest message containing "banana":
  const result = await mailhog.latestContaining('banana')

  // Log the details of this message to the console:
  console.log('From: ', result.from)
  console.log('To: ', result.to)
  console.log('Subject: ', result.subject)
  console.log('Content: ', result.text)
}

releaseMessage

mailhog.releaseMessage(id, config) → Promise

Description

Releases the mail with the given ID using the provided SMTP config.

Parameters

| Name | Type | Required | Description | | ---------------- | ------ | -------- | ---------------------------------- | | id | String | yes | message ID | | config | Object | yes | SMTP configuration | | config.host | String | yes | SMTP host | | config.port | String | yes | SMTP port | | config.email | String | yes | recipient email | | config.username | String | no | SMTP username | | config.password | String | no | SMTP password | | config.mechanism | String | no | SMTP auth type (PLAIN or CRAM-MD5) |

Returns

Returns a Promise that resolves with an http.IncomingMessage object.

Example

async function example() {
  const result = await mailhog.latestTo('[email protected]')

  const response = await mailhog.releaseMessage(result.ID, {
    host: 'localhost',
    port: '1025',
    email: '[email protected]'
  })
}

deleteMessage

mailhog.deleteMessage(id) → Promise

Description

Deletes the mail with the given ID from MailHog.

Parameters

| Name | Type | Required | Description | | ---- | ------ | -------- | ----------- | | id | String | yes | message ID |

Returns

Returns a Promise that resolves with an http.IncomingMessage object.

Example

async function example() {
  const result = await mailhog.latestTo('[email protected]')

  const response = await mailhog.deleteMessage(result.ID)

  console.log('Status code: ', response.statusCode)
}

deleteAll

mailhog.deleteAll() → Promise

Description

Deletes all mails stored in MailHog.

Parameters

None

Returns

Returns a Promise that resolves with an http.IncomingMessage object.

Example

async function example() {
  const response = await mailhog.deleteAll()

  console.log('Status code: ', response.statusCode)
}

encode

mailhog.encode(str, encoding, charset, lineLength) → String

Description

Encodes a String in the given charset to base64 or quoted-printable encoding.

Parameters

| Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | --------------------------- | | str | String | yes | | String to encode | | encoding | String | yes | utf8 | base64/quoted-printable | | charset | String | no | utf8 | Charset of the input string | | lineLength | Number | no | 76 | Soft line break limit |

Returns

Returns a String in the target encoding.

Example

const query = mailhog.encode('üäö', 'quoted-printable')
// =C3=BC=C3=A4=C3=B6

async function example() {
  // Search for "üäö" in quoted-printable encoding:
  const result = await mailhog.search(query)
}

decode

mailhog.decode(str, encoding, charset) → String

Description

Decodes a String from the given encoding and outputs it in the given charset.

Parameters

| Name | Type | Required | Default | Description | | -------- | ------ | -------- | ------- | ----------------------------- | | str | String | yes | | String to decode | | encoding | String | yes | | base64/quoted-printable | | charset | String | no | utf8 | Charset to use for the output |

Returns

Returns a String in the target charset.

Example

const output = mailhog.decode('5pel5pys', 'base64')
// 日本

Testing

1. Start Docker.
2. Install development dependencies:

   npm install

3. Run the tests:

   npm test

License

Released under the MIT license.

Author

Sebastian Tschan