AlphaMail

This add-on is operated by Comfirm AB

Transactional Email for Developers and their Apps

AlphaMail

Last Updated: 10 March 2014

This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.

The AlphaMail add-on is currently in beta.

Table of Contents

This add-on have been deprecated, and is now disabled for new installs.

AlphaMail add-on makes sending and handling Transactional Email a breeze. Unlike most Transactional Email providers, AlphaMail is data-based only. I.e. your app will not be sending tons of HTML over the wire. You’re only sending the data that is relevant. Once AlphaMail receives the data it will render it with the template that you’ve specified and send it directly to the receiver.

How is data being handled?

AlphaMail will never store any of your sensitive data. Once an email is sent, it’s data is destroyed. We only store errors, and when we do, all sensitive data is stripped. The only data that we store related to your sendings is anonymous metrics (counters indicating clicks/views/bounces). These metrics are presented to you in the AlphaMail Dashboard. For security reasons we don’t store any of the emailaddresses you send to. This means the statistics we store is anonymous, unless you choose to set an identifier when sending your emails.

Provisioning the add-on

AlphaMail can be attached to a Heroku application via the CLI:

A list of all plans available can be found on the AlphaMail add-on page.

$ heroku addons:add alphamail:starter
-----> Adding alphamail to epic-ninja-1337... done, v18 (free)

Once AlphaMail has been added a ALPHAMAIL_TOKEN setting will be available in the app configuration and will contain the Heroku API key used to access the AlphaMail API. This can be confirmed using the heroku config:get command.

$ heroku config:get ALPHAMAIL_TOKEN
4f20f7b5da0018-74150879

After installing the AlphaMail add-on you can continue by creating your first project. A project in AlphaMail is essentially an email. It holds the template, it’s settings and displays the send statistics. Login to the AlphaMail Dashboard as shown below from the terminal. If this is your first time signing in, a guide will start which will show you how to get started.

$ heroku addons:open alphamail
Opening alphamail for epic-ninja-1337…

Local setup

AlphaMail automatically sets environment variables on your Heroku servers, but sometimes you may need to recreate the environment locally. Foreman aims to solve this for you. You can save the environment variables in your .env file and let Foreman do the rest.

$ bash -c 'echo "ALPHAMAIL_TOKEN=`heroku config:get ALPHAMAIL_TOKEN`" >> .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Dashboard

For more information on the features available within the AlphaMail Dashboard please see the docs at http://app.amail.io/#/docs/.

The AlphaMail dashboard allows you to manage projects, see statistics, and edit/create templates.

The dashboard can be accessed via the CLI:

$ heroku addons:open alphamail
Opening alphamail for epic-ninja-1337…

or by visiting the Heroku apps web interface and selecting the application in question. Select AlphaMail from the Add-ons menu.

Sending with Ruby

1) Install dependencies. This library relies on the json gem in order to function.

$ gem install json

2) Install the latest AlphaMail client library gem. Note that the json gem is required for the alphamail gem to work.

$ gem install alphamail

3) Create a new file alphamail_test.rb and use the code below:

myService = AlphaMail::EmailService.new('http://api.amail.io/v1', ENV["ALPHAMAIL_TOKEN"])

am_res = myService.queue(AlphaMail::MessagePayload.new(
    12345, # ID of your "Test Project" project
    'am-1337', # Receiver ID (string or integer)
    AlphaMail::Contact.new('AlphaMail Test', 'some-sender@amail.io'), # Sender
    AlphaMail::Contact.new('John Doe', 'john.doe@someguysmail.tld'), # Receiver
    someObject # A JSON serializable object
))

Sending with Node.js

1) Install the latest Node.js client library using npm.

$ npm install alphamail

2) Create a new file alphamail_test.js and use the code below.

Notice the use of process.env.ALPHAMAIL_TOKEN. This is your AlphaMail API token, provided by Heroku.

var alphamail = require('alphamail');
var emailService = new alphamail.EmailService(process.env.ALPHAMAIL_TOKEN);

var data = {
    id: "abc-123-456",
    name: "Some Guy",
    profile_url: "http://domain.com/profile/ABC-123-456/",
    recommended_profiles: [
        {
            id: "abc-222-333",
            name: "Jane Joe",
            profile_url: "http://domain.com/profile/ABC-222-333/",
            profile_image_url: "http://img.domain.com/profile/abc-222-333.jpg",
            age: 24
        }
    ]
};

var payload = new alphamail.EmailMessagePayload()
    .setProjectId(12345) // ID of your "Test Project" project
    .setSender(new alphamail.EmailContact("AlphaMail Test", "some-sender@amail.io"))
    .setReceiver(new alphamail.EmailContact("John Doe", "john.doe@someguysmail.tld"))
    .setBodyObject(data);

emailService.queue(payload, function(error, result){
    if(error){
        console.log(error);
        return;
    }
    console.log("Email sent! ID = " + result);
});

3) Questions? See the GitHub page for a more detailed documentation.

Sending with PHP

1) Download and unpack the latest PHP client library from GitHub.

$ wget -O alphamail_php.zip https://github.com/comfirm/alphamail-php5-client/archive/master.zip
$ unzip alphamail_php.zip

2) Create a new file alphamail_test.php and use the code below. Remember to check so that ‘emailservice.class.php’ is referenced correctly.

include_once("./comfirm.alphamail.client/emailservice.class.php");

$email_service = new AlphaMailEmailService($_ENV['ALPHAMAIL_TOKEN']);

$message = array(
    "id" => "abc-123-456",
    "name" => "Some Guy",
    "profile_url" => "http://domain.com/profile/ABC-123-456/"
);

$payload = EmailMessagePayload::create()
    ->setProjectId(12345) // ID of your "Test Project" project
    ->setSender(new EmailContact("AlphaMail Test", "some-sender@amail.io"))
    ->setReceiver(new EmailContact("John Doe", "john.doe@someguysmail.tld"))
    ->setBodyObject($message);

try
{
    $response = $email_service->queue($payload);
    printf("Mail successfully sent! ID = %s", $response->result);
}
catch(AlphaMailServiceException $exception)
{
    printf("Error! %s (%s)", $exception->getMessage(), $exception->getErrorCode());
}

Sending with Java

1) Download and unpack the latest Java client library from GitHub.

$ wget -O alphamail_java.zip https://github.com/comfirm/alphamail-j2ee-client/archive/master.zip
$ unzip alphamail_java.zip

2) Create a new applet and use the code below.

import com.comfirm.alphamail.services.client.AlphaMailService;
import com.comfirm.alphamail.services.client.DefaultAlphaMailService;
import com.comfirm.alphamail.services.client.entities.EmailContact;
import com.comfirm.alphamail.services.client.entities.EmailMessagePayload;
import com.comfirm.alphamail.services.client.entities.ServiceIdentityResponse;

AlphaMailService emailService = new DefaultAlphaMailService()
    .setServiceUrl("http://api.amail.io/v1/")
    .setApiToken(System.getenv("ALPHAMAIL_TOKEN"));

EmailMessagePayload payload = new EmailMessagePayload()
    .setProjectId(12345) // ID of your "Test Project" project
    .setSender(new EmailContact("AlphaMail Test", "some-sender@amail.io"))
    .setReceiver(new EmailContact("John Doe", "john.doe@someguysmail.tld"))
    .setBodyObject(someObject); // JSON serializable object

ServiceIdentityResponse response = emailService.queue(payload);

Sending with Python

1) Download and unpack the latest Python client library from GitHub.

$ wget -O alphamail_python.zip https://github.com/comfirm/alphamail-python-client/archive/master.zip
$ unzip alphamail_python.zip

2) Create a new file alphamail_test.py and use the code below:

# Import from src folder
import os, sys
lib_path = os.path.abspath('src')
sys.path.append(lib_path)

from comfirm_alphamail_client import *

email_service = AlphaMailEmailService('http://api.amail.io/v2/', os.environ['ALPHAMAIL_TOKEN'])

payload = EmailMessagePayload()
payload.set_project_id(12345) # ID of your "Test Project" project
payload.set_sender(EmailContact('AlphaMail Test', 'some-sender@amail.io'))
payload.set_receiver(EmailContact('John Doe', 'john.doe@someguysmail.tld', 'am-1337')) # The 3rd argument is the optional receiver id and should be either a string or an integer
payload.set_body_object(object) # A JSON serializable object

email_service.queue(payload)

Sending with Perl

1) Download and unpack the latest Perl client library from GitHub.

$ wget -O alphamail_perl.zip https://github.com/comfirm/alphamail-perl-client/archive/master.zip
$ unzip alphamail_perl.zip

2) Install dependencies

$ cpan install HTTP::Request
$ cpan install LWP
$ cpan install JSON

3) Install the library

$ perl Makefile.PL
$ make
$ make test
$ make install

4) Create a new file alphamail_test.pl and use the code below:

#!/usr/bin/perl

require 'src/lib/AlphaMail.pm';

use strict;
use utf8;
use Switch;
use AlphaMail;

my $service = new AlphaMailEmailService(
    "http://api.amail.io/v2/", # Service URL
    $ENV{'ALPHAMAIL_TOKEN'} # API Token
);

my $payload = new EmailMessagePayload();
$payload->projectId(12345); # ID of your "Test Project" project
$payload->sender(new EmailContact("AlphaMail Test", "some-sender@amail.io", 0)); # Sender
$payload->receiver(new EmailContact("John Doe", "john.doe@someguysmail.tld", "am-1337)); # Receiver, the 3rd argument is the optional receiver id and should be either a string or an integer
$payload->bodyObject($jsonSerializableObject); # Body Object

my $response = $service->queue($payload);

Sending with Erlang

1) Download and unpack the latest Erlang client library from GitHub.

$ wget -O alphamail_erlang.zip https://github.com/comfirm/alphamail-erlang-client/archive/master.zip
$ unzip alphamail_erlang.zip

2) Install dependencies.

  • This library depends on mochijson which is a part of mochiweb.

3) Create a new file alphamail_erlang.erl and use the code below:

-module(example_simple).
-export([sendmail/0]).

sendmail() ->
    Service = alphamail:email_service(os:getenv("ALPHAMAIL_TOKEN")),
    Payload = alphamail:message_payload(
        1996, % ID of "New Project" project
        alphamail:email_contact(<<"AlphaMail Test">>, <<"some-sender@amail.io">>), % Sender
        alphamail:email_contact(<<"John Doe">>, <<"john.doe@someguysmail.tld">>, <<"am-1337">>), % Receiver, the 3rd argument is the optional receiver id and should be either a string or an integer
        % JSON serializable payload data
        [
            {"message", <<"Hello world like a boss!">>}, % Represents the <# payload.message #> in our template
            {"some_other_message", <<"And to the rest of the world! Chíkmàa! مرحبا! नमस्ते! Dumelang!">>} % Represents the <# payload.some_other_message #> in our template
        ]
    ),
    alphamail:queue(Service, Payload).

Troubleshooting

How can I import emails into AlphaMail?

Since AlphaMail is a Transactional Email service only, we don’t support importing of emails or creation of lists in the system. If you want to send newsletters, there are great services such as MailChimp or CampaignMonitor available. AlphaMail’s goal is to become the best Transactional Email provider out there.

How do I send to multiple recipients at the same time?

Since the AlphaMail API is a “transactional only” API, support for multiple recipients is currently not available. If you want to send the same message to several recipients, our recommendation is currently to just repeat the message for each recipient that you want to send to.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade alphamail:newplan
-----> Upgrading alphamail:newplan to epic-ninja-1337... done, v18 ($49/mo)
       Your plan has been updated to: alphamail:newplan

Removing the add-on

AlphaMail can be removed via the CLI.

This will unlink your AlphaMail account from Heroku! This action cannot be undone!

$ heroku addons:remove alphamail
-----> Removing alphamail from epic-ninja-1337... done, v20 (free)

Support

All AlphaMail support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@amail.io.