How to implement Freshmail form on your website

April 13, 2016

After reading this article you will be able to:

  • Add subscriber with traditional form
  • Add subscriber with AJAX request
  • Use Freshmail Rest API with Node modules to add subscriber

This article will show you multiple ways with which you can easily add subscribers to your Freshmail lists. With Freshmail Rest API you will be able to manage all your list, subscribers and more, with a few lines of code. Let’s start.

Simplest Way

Of course, the simplest way is to implement form prepared by Freshmail. All you have to do is copy and paste your code in suitable place on your website. This code looks like code below:

<form method="post" action="https://app.freshmail.com/pl/actions/subscribe/">
<br /><div><span style="display: none !important;"><br /><a href="http://freshmail.com/" style="display: inline !important;">best email marketing</a> powered by FreshMail</span></div><br />
<input type="hidden" name="subscribers_list_hash" value="YOUR_SUBSCRIBER_LIST_HASH" /><br />
<label for="freshmail_email">Email</label><br /><br />
<input type="text" id="freshmail_email" name="freshmail_email"/> <br/><br />
<input type="submit" value="Wyślij" /><br />
</form>

This code will simply create an email imput and a send button. You should also change YOUR_SUBSCRIBER_LIST_HASH to your own list hash.

After completing form user will see an information about confirming his email. it It is as simple as that.

AJAX request

Next way to add subscriber to a list is to use AJAX request. My request is quite simply but effective.

var data = {
  subscribers_list_hash: "YOUR_SUBSCRIBER_LIST_HASH",
  freshmail_email: form_email
};

var url = "https://app.freshmail.com/pl/actions/subscribe/";

var post = function(url, fields) {
  var $form = $('<form>', {
      action: url,
      method: 'post'
  });
  $.each(fields, function(key, val) {
      $form.append('<input name="'+key+'" value="'+val+'">');
  });
  $form.submit();
}

post(url, data);

You also need to create your own form and set function with above code as a form action. You will also notice that after sending form, user will see an information about email confirmation. So what are the benefits of this way than first way? You can create as complex forms as you want, do whatever you want with this data and then send AJAX request to add subscriber. I think that this way can be quite useful in some cases.

Using Freshmail Rest API

This is a most complex way of adding subscriber to list, but also is the most useful. After learning how to use Rest API, you will be able to add, delete, modify users and list and also getting information about your list and users. This could be useful for example to displaying and managing your clients on your own website, you could not be depend on Freshmail administration panel.

So, how to do that? To show an example, I will use NodeJS and two npm modules: sha1 and request. What are those? SHA1 will let us create a encrypted hash for Freshmail authentication and request will be used to send our data from NodeJS.

To demonstrate this, I will use the following versions of modules:

"request": "^2.69.0",
"sha1": "^1.1.1"

Node version: 5.10.1

I think that you could also use older versions of those modules, but I haven’t test them, so do it on your own risk.

var sha1    = require('sha1');
var request = require('request');

var contentType = 'application/json';
var apiKey      = 'YOUR_API_KEY';
var apiSecret   = 'YOUR_API_SECRET_KEY';
var GET_data    = '/rest/subscriber/add';
var JSON_data   = JSON.stringify({
                  email: form_email,
                  list: "YOUR_SUBSCRIBER_LIST_HASH",
                  state: 1,
                });

var apiSign     = sha1( apiKey + GET_data + JSON_data + apiSecret )

var options = {
    method: 'POST',
    url: 'https://api.freshmail.com/rest/subscriber/add',
    headers: {
        'Content-Type': contentType,
        'X-Rest-ApiKey': apiKey,
        'X-Rest-ApiSign': apiSign
    },
    body: JSON_data,
};

function callback(error, response, body) {
    console.log(error);
    if (!error && response.statusCode == 200) {
        var info = JSON.parse(body);
        console.log("Success", info)
    } else{
        console.log("Error : " ,error);
        console.log("Error : " ,body);

    }
}

request(options, callback);

From the beginning, first we added our npm modules. Then we assigned values that we will use to authenticate and send data to API. You should replace YOUR_API_KEY, YOUR_SUBSCRIBER_LIST_HASH and YOUR_API_SECRET_KEY with your own values. You could easily find them on Freshmail website.

JSON_data is our data that we want to send to API. To add a subscriber we need his email, our list and state. State 1 means that user will have an active status on subscription list immediately.

var apiSign = sha1( apiKey + GET_data + JSON_data + apiSecret ) is used to create a needed encrypted hash string for authentication.

In options we will place our methods, API URL and headers. To correctly send a API request to Freshmail you need those three headers:

headers: {
    'Content-Type': contentType,
    'X-Rest-ApiKey': apiKey,
    'X-Rest-ApiSign': apiSign
},

body: JSON_data in body we place a stringified JSON object we use to store data.

Callback function

function callback(error, response, body) {
    console.log(error);
    if (!error && response.statusCode == 200) {
        var info = JSON.parse(body);
        console.log("Success", info)
    } else{
        console.log("Error : " ,error);
        console.log("Error : " ,body);

    }
}

It is a very simple example of getting success and error messages from API. This will console out information to your NodeJS console. For complete reference of available error codes see Freshmail Rest API documentation.

request(options, callback) - here we call request module function with our options object and callback functions.

This code is sufficient to get data from, and send data to Rest API.

Resources:

Kuba Wyrobek Founder, Meteor Developer
Grzegorz Oleksy Junior Meteor Developer