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

constmailhog=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 availablecount: Number,// Number of results returnedstart: Number,// Offset for the range of results returneditems: Array// List of mail object items}

The individual mail object items have the following properties:

{ID: String,// Mail IDtext: String,// Decoded mail text contenthtml: String,// Decoded mail HTML contentsubject: String,// Decoded mail Subject headerfrom: String,// Decoded mail From headerto: String,// Decoded mail To headercc: String,// Decoded mail Cc headerbcc: String,// Decoded mail Bcc headerreplyTo: String,// Decoded mail Reply-To headerdate: Date,// Mail Date headerdeliveryDate: Date,// Mail Delivery-Date headerattachments: Array// List of mail attachments}

The individual attachments have the following properties:

{name: String,// Filenametype: String,// Content-Typeencoding: String,// Content-Transfer-EncodingBody: String// Encoded content}

Example

asyncfunctionexample(){// Retrieve the latest 10 messages:constresult=awaitmailhog.messages(0,10)// Log the details of each message to the console:for(letitemofresult.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 availablecount: Number,// Number of results returnedstart: Number,// Offset for the range of results returneditems: Array// List of mail object items}

The individual mail object items have the following properties:

{ID: String,// Mail IDtext: String,// Decoded mail text contenthtml: String,// Decoded mail HTML contentsubject: String,// Decoded mail Subject headerfrom: String,// Decoded mail From headerto: String,// Decoded mail To headercc: String,// Decoded mail Cc headerbcc: String,// Decoded mail Bcc headerreplyTo: String,// Decoded mail Reply-To headerdate: Date,// Mail Date headerdeliveryDate: Date,// Mail Delivery-Date headerattachments: Array// List of mail attachments}

The individual attachments have the following properties:

{name: String,// Filenametype: String,// Content-Typeencoding: String,// Content-Transfer-EncodingBody: String// Encoded content}

Example

asyncfunctionexample(){// Search the latest 10 messages containing "banana":constresult=awaitmailhog.search('banana','containing',0,10)// Log the details of each message to the console:for(letitemofresult.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 IDtext: String,// Decoded mail text contenthtml: String,// Decoded mail HTML contentsubject: String,// Decoded mail Subject headerfrom: String,// Decoded mail From headerto: String,// Decoded mail To headercc: String,// Decoded mail Cc headerbcc: String,// Decoded mail Bcc headerreplyTo: String,// Decoded mail Reply-To headerdate: Date,// Mail Date headerdeliveryDate: Date,// Mail Delivery-Date headerattachments: Array// List of mail attachments}

The individual attachments have the following properties:

{name: String,// Filenametype: String,// Content-Typeencoding: String,// Content-Transfer-EncodingBody: String// Encoded content}

Example

asyncfunctionexample(){// Search the latest message from "test@example.org":constresult=awaitmailhog.latestFrom('test@example.org')// 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 IDtext: String,// Decoded mail text contenthtml: String,// Decoded mail HTML contentsubject: String,// Decoded mail Subject headerfrom: String,// Decoded mail From headerto: String,// Decoded mail To headercc: String,// Decoded mail Cc headerbcc: String,// Decoded mail Bcc headerreplyTo: String,// Decoded mail Reply-To headerdate: Date,// Mail Date headerdeliveryDate: Date,// Mail Delivery-Date headerattachments: Array// List of mail attachments}

The individual attachments have the following properties:

{name: String,// Filenametype: String,// Content-Typeencoding: String,// Content-Transfer-EncodingBody: String// Encoded content}

Example

asyncfunctionexample(){// Search the latest message to "test@example.org":constresult=awaitmailhog.latestTo('test@example.org')// 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 IDtext: String,// Decoded mail text contenthtml: String,// Decoded mail HTML contentsubject: String,// Decoded mail Subject headerfrom: String,// Decoded mail From headerto: String,// Decoded mail To headercc: String,// Decoded mail Cc headerbcc: String,// Decoded mail Bcc headerreplyTo: String,// Decoded mail Reply-To headerdate: Date,// Mail Date headerdeliveryDate: Date,// Mail Delivery-Date headerattachments: Array// List of mail attachments}

The individual attachments have the following properties:

{name: String,// Filenametype: String,// Content-Typeencoding: String,// Content-Transfer-EncodingBody: String// Encoded content}

Example

asyncfunctionexample(){// Search the latest message containing "banana":constresult=awaitmailhog.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

asyncfunctionexample(){constresult=awaitmailhog.latestTo('test@example.org')constresponse=awaitmailhog.releaseMessage(result.ID,{host: 'localhost',port: '1025',email: 'test@example.org'})}

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

asyncfunctionexample(){constresult=awaitmailhog.latestTo('test@example.org')constresponse=awaitmailhog.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

asyncfunctionexample(){constresponse=awaitmailhog.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

constquery=mailhog.encode('üäö','quoted-printable')// =C3=BC=C3=A4=C3=B6asyncfunctionexample(){// Search for "üäö" in quoted-printable encoding:constresult=awaitmailhog.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

constoutput=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