postmailer/README.md

HTTP POST -> SMTP proxy, as Express middleware

# postmailer

An Express middleware implementing the "HTTP POST mail" principle as an HTTP-to-SMTP proxy.

The principle is that all POST requests to a user's contact URL (e.g. `/~username`) should be received as messages by that user.  This module is a proxy to make this work using existing email infrastructure, by resending received messages using SMTP.

The module is an Express middleware, and accepts raw resources (e.g. text, HTML, images or other documents) or url-encoded forms.  Multipart messages/forms are not currently supported - any external resources should be referenced by URL or sent as separate messages.

## Usage

```javascript
var express = require('express'), app = express();
var postmailer = require('postmailer');

app.use(postmailer({
	mapping: {
		url: '/contact',
		email: 'someone@example.com'
	}
}));
```

Unless `Content-Disposition:` is set to `attachment` in the POST request, plain-text and HTML are unchanged, and images are displayed inline in the email.  Otherwise, the document is included as an attachment.

## Options

* `options.mapping` - defines the mapping between URLs and email addresses. See below for more detail.
* `options.domain` - a protocol+domain (or list of such) to be used as a prefix (e.g. `https://example.com`) for relative URLs
* `options.transport` - *optional but recommended:* transport for `nodemailer` to use (see below), defaults to direct mailer
* `options.maxInline` - *optional:* maximum size (in bytes) of inline content, where larger documents are sent as attachments.  Defaults to `500*1024` (500kb)
* `options.webForm` - *optional:* whether a friendly page should be displayed on GET requests.  Defaults to `true`
    * **boolean** - enable/disable (default template)
    * **string** - template file, with two parameters `{{username}}` and `{{url}}`
    * **function** - template function, with two arguments `username` and `url`
* `options.minifyForm` - *optional:* whether the web form should be minified (HTML/JS/CSS) using the `html-minifier` package.  Defaults to `false`

## Transport

You can provide a custom transport for sending mail.  This is passed to `nodemailer.createTransport()`, and can therefore be either a transport (e.g. from one of the `nodemailer-*-transport` modules) or an object with parameters for the SMTP transport (default):

```javascript
options.transport = {
	host: 'smtp.mailer.example.com',
	port: 25,
	auth: {
		user: 'username',
		pass: 'password'
	}
}
```

If no details/transport is supplied, this module defaults to the [direct mailer](https://www.npmjs.com/package/nodemailer-direct-transport).  Direct SMTP connections (particularly from non-static IPs) are rejected by some mail services (e.g. Gmail) - if you want to send to these services, consider using a mailer such as [Mandrill](https://www.mandrill.com/) or [Mailgun](http://www.mailgun.com/).

## Mapping

The `options.mapping` property can either be a mapping object, or an array of mapping objects.

A mapping object (used in `options.mapping`) has the following properties:

* `.url` - a URI Template (or array of templates) for the URLs
* `.email` - a URI Template for the email address
* `.restricted` - whether this mapping is hidden from public use (defaults to `false`).

To convert between URLs and email addresses, the template for one is deconstructed, and the same parameters applied to the other.  **Order matters**: when converting to URL(s), preference is given to mappings listed first, and when converting to email address, only the first is used.

For "local" URLs, it's simplest to use relative URLs with absolute paths (e.g. `/contact`).  These will be converted to/from absolute URLs when necessary, using the `options.domain` parameter.

## SMTP -> HTTP proxy

This module converts applicable URLs in the message headers to email addresses.  The goal is to allow users to specify a URL as a `Reply-To:` address or similar, so that they can in theory communicate entirely in POST requests.

However, if the message is actually being forwarded to an email account, these URLs need to be translated into email addresses to be accepted by the mail client.  The idea is that you can have a "catch-all" mapping at the end of your mapping list:

```javascript
{
	url: "{+url}",
	email: "post+{url}@mydomain.com",
	open: false
}
```

You would then need an SMTP-to-HTTP gateway that used the same mapping, and translated replies/etc. back into POST requests (the `open: false` setting means that this proxy would only work if a known/open user was involved.).

This is currently under development.

## Default web form

The default web form (provided on GET requests to a valid endpoint) contains a short description of what the endpoint is, some examples (with `curl`) and an AJAX interface to send messages directly from the browser.

It also detects (using JavaScript) whether it's embedded in an IFrame, and presents a cut-down UI with just two fields (email/message) and a "send" button, suitable for embedding as a contact form on other websites such as blogs.

## TTD

* bounce messages (both directions)