Setting Up Haraka to send to mailchimp/sendgrid/SES etc

One really useful way to use Haraka at a business is to be a local fast cache to forward on to mailchimp/sendgrid/SES or one of the many available transactional mail senders out there. These services offer bounce management, tracking, and also manage deliverability for you, and yet often their sending systems are slow, which can affect your app. By installing Haraka locally you can keep all those benefits, but have your system return from sending mail much faster.

First, install haraka and create an instance of it:

$ sudo npm install -g Haraka
... # lots of output
$ haraka -i /var/apps/haraka

Now edit `/var/apps/haraka/config/plugins` to define what Haraka plugins will get loaded. Here’s my simple config for this setup:

# this lets you view how much stuff your haraka instance is doing
# this lets you receive inbound mail, but is mostly not required
# this is a custom plugin I'll detail below
# this lets you configure who can relay (i.e. your app)
# Check mail headers are valid
# this lets you configure where inbound mail goes (also mostly not required)
# this is just a safety net

You’ll need an entry in the `config/host_list` file:

$ hostname > /var/apps/haraka/config/host_list

You’ll want to allow localhost to relay:

$ echo > /var/apps/haraka/config/relay_acl_allow
$ echo ::1 >> /var/apps/haraka/config/relay_acl_allow

Copy this into your `/var/apps/haraka/config/relay.ini` file:


Prevent `smtp_forward` from processing outbound mail:

$ echo 'enable_outbound=false' > /var/apps/haraka/config/smtp_forward.ini

Edit your `smtp.ini` file to make it listen on a higher port so you don’t have to listen on port 25 by setting the `listen=` line to: listen=[::0]:2525, and set the `nodes=` line to use as many CPUs as you think is reasonable for your setup.

Finally, copy this plugin into `/var/apps/haraka/plugins/relay_via_external`:

var external_smtp = {
    auth_user: '<your username here>',
    auth_pass: '<enter password here>',
    priority: 0,
    exchange: 'smtp.mailgun.org', # or whoever else

exports.hook_get_mx = function (next, hmail, domain) {
    // All relaying goes via external service
    return next(OK, external_smtp);

Remember to edit the username and password – get them from your mail service provider.

And that’s it. There are various ways of launching Haraka (see the contrib directory on github) which keep it starting at startup. But to test it you can simply launch: `haraka -c /var/apps/haraka`.

Now just make your app use localhost on port 2525 as your mail server, with no authentication necessary, and your mail will go out MUCH faster.


6 thoughts on “Setting Up Haraka to send to mailchimp/sendgrid/SES etc

  1. vavaivivian says:


    Does the above configuration still can be applied on latest version or do I need to simply using smtp_forward plugins?


    • Yes it still works.

      The smtp_forward plugin works a bit differently – if you get a 4xx error from the upstream provider, smtp_forward won’t queue the mail for retry – it will send that status back to your application immediately.

  2. vavaivivian says:

    I’m trying with the above config, but it has an error “[CRIT] [-] [core] Caught exception: “Loading plugin relay_via_external failed: No plugin with this name found”

    root@3b27863739c2:/# ls /var/apps/haraka/plugins/
    root@3b27863739c2:/# cat /var/apps/haraka/plugins/relay_via_external
    var external_smtp = {
    auth_user: ”,
    auth_pass: ‘MyStrongPassword’,
    priority: 0,
    exchange: ‘relay-server.excellent.tld’, # or whoever else

    exports.hook_get_mx = function (next, hmail, domain) {
    // All relaying goes via external service
    return next(OK, external_smtp);

    What’s the missing step?

  3. vavaivivian says:

    My bad, forgot to add .js on the /var/apps/haraka/plugins/relay_via_external, itu should be /var/apps/haraka/plugins/relay_via_external.js :-)

    Anyway, how to define custom port for external relay, let say I would like to use port 2525 on the sendgrid/mailchimp side?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s