email2pdf/README.md

94 lines
3.9 KiB
Markdown
Raw Permalink Normal View History

2014-09-19 16:53:57 +01:00
# email2pdf
2014-09-19 16:30:15 +01:00
2018-10-12 12:11:29 +01:00
[![Travis CI
Status](https://travis-ci.org/andrewferrier/email2pdf.svg?branch=master)](https://travis-ci.org/andrewferrier/email2pdf)
2015-12-26 18:56:00 +00:00
2014-12-18 18:16:12 +00:00
email2pdf is a Python script to convert emails to PDF from the command-line.
It is not interactive (it doesn't run from a browser or have a GUI), but is
intended to be run as a [mail delivery
2014-11-13 09:22:47 +00:00
agent](http://en.wikipedia.org/wiki/Mail_delivery_agent) - it won't retrieve
emails for you, but it will take them from standard input as an MDA will and
2015-08-20 00:51:18 +02:00
'deliver' them to PDF files. It is well-placed to use together with
[getmail](http://pyropus.ca/software/getmail/), perhaps run on a schedule
using [cron](https://en.wikipedia.org/wiki/Cron) or similar. You can also just
use it as a standalone utility to convert a raw email (normally an
2015-08-20 00:51:18 +02:00
[.eml](https://en.wikipedia.org/wiki/Email#Filename_extensions) file) to a
PDF. Type `email2pdf --help` for more information on usage and options
available.
2014-09-19 16:53:57 +01:00
For more information on hacking/developing email2pdf, please see
[HACKING.md](https://github.com/andrewferrier/email2pdf/blob/master/HACKING.md).
2015-08-20 00:51:18 +02:00
Note that use is subject to the [license
conditions](https://github.com/andrewferrier/email2pdf/blob/master/LICENSE.txt).
2014-09-19 16:53:57 +01:00
## Installing Dependencies
2014-10-12 13:40:48 +01:00
Before you can use email2pdf, you need to install some dependencies. The
instructions here are split out by platform:
2014-12-18 18:16:12 +00:00
2014-12-21 21:39:24 +00:00
### Debian/Ubuntu
2014-12-18 18:16:12 +00:00
* [wkhtmltopdf](http://wkhtmltopdf.org/) - Install the `.deb` from
http://wkhtmltopdf.org/ rather than using apt-get to minimise the
dependencies you need to install (in particular, to avoid needing a package
manager).
2015-01-18 16:08:54 +00:00
* [getmail](http://pyropus.ca/software/getmail/) - getmail is optional, but it
works well as a companion to email2pdf. Install using `apt-get install
getmail`.
2015-01-18 16:08:54 +00:00
* Others - there are some other Python library dependencies. Run `make
builddeb` to create a `.deb` package, then install it with `dpkg -i
mydeb.deb`. This will prompt you regarding any missing dependencies.
2015-01-18 16:08:54 +00:00
### OS X
2014-12-18 18:16:12 +00:00
* [wkhtmltopdf](http://wkhtmltopdf.org/) - Install the package from
http://wkhtmltopdf.org/downloads.html.
2014-12-18 18:16:12 +00:00
* [getmail](http://pyropus.ca/software/getmail/) - TODO: This hasn't been
tested, so there are no instructions here yet! Note that getmail is
optional.
2014-12-20 16:13:46 +00:00
* Install [Homebrew](http://brew.sh/)
2014-12-20 16:13:46 +00:00
2015-07-14 21:19:21 +01:00
* `xcode-select --install` (for lxml, because of
[this](http://stackoverflow.com/questions/19548011/cannot-install-lxml-on-mac-os-x-10-9))
* `brew install python3` (or otherwise make sure you have Python 3 and `pip3`
available).
2014-10-12 16:15:18 +01:00
* `brew install libmagic`
* `pip3 install -r requirements.txt`
## Configuring getmail
getmail is not strictly a dependency, but when it is combined with email2pdf,
it can be used to retrieve new emails from a remote IMAP server and
automatically convert them to PDFs locally. The
[`getmailrc.sample`](https://github.com/andrewferrier/email2pdf/blob/master/getmailrc.sample)
file in the repository can be used as a starting point for your own getmailrc
to do this. Note that the sample will need editing, of course - see the
getmail documentation for more information on that. Also, it is configured by
default to *delete* remote emails from the server once they are converted - be
careful with that. You might want to consider setting up your crontab
something like this:
2014-10-12 16:15:18 +01:00
2015-07-01 17:52:16 -05:00
```
@hourly getmail --verbose | logger
2015-07-01 17:52:16 -05:00
```
2014-10-12 16:15:18 +01:00
This will ensure that getmail is invoked hourly to fetch email, and log its
output to syslog.
2015-11-19 10:55:49 +04:00
If your mailserver is unreliable, you might want to consider wrapping the getmail
cron job with [cromer](https://github.com/andrewferrier/cromer).
2016-01-05 12:27:50 +00:00
## Configuring procmail
I don't have any direct experience using procmail with email2pdf, so don't have any
specific setup steps, although I understand it can be made to work. You should be
aware that currently there is an outstanding issue with I/O encodings with procmail
that you may need to work around - see [issue #76](https://github.com/andrewferrier/email2pdf/issues/76) for more information.