node package manager
Stop writing boring code. Discover, share, and reuse within your team. Create a free org »



Download email attachments via IMAP

Build Status

download-email-attachments downloads all attachements of an email account to a directory and optionally do some postprocessing. It can either be required as module or used as a command line tool.

Command Line Interface

# install download-email-attachments globally
npm install -g download-email-attachments
# download all attachments of (password: secret) since beginning of 2015-01-12
download-email-attachments "" \
  --directory ./files \
  --filename-template "{day}-{filename}" \
  --filename-filter ".xlsx?$" \
  --timeout 3000 \
  --since 2015-01-12

Using as module

var onEnd = function (result) {
  if (result.error) {
var downloadEmailAttachments = require('download-email-attachments');
  invalidChars: /[^A-Z]/g, //Regex of Characters that are invalid and will be replaced by X 
  account: '""', // all options and params besides account are optional 
  directory: './files',
  filenameTemplate: '{day}-{filename}',
  filenameFilter: /.xlsx?$/,
  timeout: 3000,
  log: {warn: console.warn, debug:, error, console.error, info: },
  since: '2015-01-12',
  lastSyncIds: ['234', '234', '5345'] // ids already dowloaded and ignored, helpful because since is only supporting dates without time 
  attachmentHandler: function (attachmentData, callback, errorCB) {
}, onEnd)


You have to pass an imap account with password, the format is:

  • username If username contains @ or :, put it in quotes, e.g. `""
  • password If password contains @ or :, put it in quotes, e.g. `joe:"123:@456"
  • host This is the imap domain
  • port Optional, defaults to 993

--directory / directory

Optional. Defaults to ./

Directory where attachments shall be downloaded to.

--filename-template / filenameTemplate

Optional. Defaults to {filename}

Filenames the attachments shall be saved as. Using / will create subfolders. The following placeholders are available

  • {filename}, e.g. data.xls
  • {basename}, e.g. data
  • {extension}, e.g. xls
  • {day}, e.g. 2015-01-01
  • {recipientAddress}, e.g.
  • {senderAddress}, e.g.
  • {id}, unique content ID, e.g. c361f45d-98b6-9b18-96ac-f66aee2cb760
  • {nr}, starts at 1 and increments for every stored file.

--filename-filter / filenameFilter


Pass a regular expression, only attachments matching it will be downloaded.

--timeout / timeout

Optional, defaults to 10000

Timeout in millisecond to wait for data from the imap server until closing the connection.

--since / since

Optional. Defaults to today's date in YYYY-MM-DD format

Local setup

git clone
cd download-email-attachments
npm install

Run all tests

npm test

Note: There is no full stack test yet, because of the complexity of stubbing an imap server. If someone could help here, that'd be much appreciated! Ping me