Documentation

How to send an email using a Docklet associated with a template

To send one or more emails, a request should be made to the endpoint using POST with a valid JSON. The unique attribute necessary is the to, a list with one or more containers. Each list item is a dictionary containing the following fields:

  • email*
  • name
  • merge_var
  • attachment

*required

It’s mandatory to inform the recipient’s email. The other fields are optional.

The sender's data, Name, Email and Subject will be rescued from the saved template and used to format the email that will be sent.

The merge_vars field is a dictionary that will be injected into the template context to customize the fields. In this dictionary you can inject as many customization variables as you wish. This context even affects the Subject that can be customized as well.

"merge_vars": {"birthdate":"02/08/1984", "gender":"male"}

The fields customization in the Template is made by changing automatically the template variables for the variables injected by merge_vars. The syntax used in the templates is the Jinja2 syntax with all features.

Let's see a complete example:

Template

<html>
<body>
Customization test<br>
Name: {{contact.name}}<br>
Email: {{contact.email}}<br>
Birthdate: {{birthdate}}<br>
Gender: {{gender}}<br>
</body>
</html>

Note that the variable fields are delimited by {{}}. Whenever there is a delimited content by {{}} the system will try changing variables injected through merge_vars.

That even goes for the email Subject such as:

Subject: Welcome {{contact.name}}

RESTful Request

Run a request

Endpoint: http://yourdomain.ecentry.io/api/maildocker/v1/mail/
Method: post
Authorization: Basic
Content-Type: application / json

{
    "to": [{
        "name": "Full Name",
        "email": "email@email.com",
        "merge_vars": {"birthdate":"02/08/1984", "gender":"male"}
    }]
}

Here is the same example sent by Curl

"curl -­?v -­?-­?user 933ff2214029fffe19c:8107ff48ff6bc4fb19
http://yourdomain.ecentry.io/api/maildocker/v1/mail/
-­?H "Content-­?Type: application/json"
-­?d {"to": [{
                "name":"Full Name",
                "email":"email@email.com",
                "merge_vars": {"birthdate":"02/08/1984", "gender":"male"}
           }]
    }

The Basic Authorization must be used, passing the API KEY and the API SECRET as data for authentication.

Result

The result of the post, if the JSON is correctly formatted and the authorization was given, is a JSON containing a list of each one of the emails sent and a unique event identifier.

201 Created

[
    {
        "email": "email@email.com",
        "uuid": "44dyfE5GawzwfbG7Nz5r-­?9SpeG"
    }
]

This unique identifier can be used to rescue the result of that sending or better, the chain of events resulting from that sending.

The personalized email will be sent with the following content:

<html>
<body>
Customization test<br>
Name:Full Name<br>
Email: email@email.com<br>
Birthdate: 02/08/1984<br>
Gender: male<br>
</body>
</html>

Note your data has been replaced.

Events Recovery

Maildocker uses the concept of events and event chain. Each email sent, opening, click, unsubscribe or bounce is treated as an event, and they are all related to one chain of events that starts with the sending.

To retrieve all events inside the system events a call must be made using the following data:

Endpoint: http://yourdomain.ecentry.io/api/maildocker/v1/event/
Method: get
Authorization: Basic

The result will be:

{
    "info": {
        "last_event": "email_send",
        "last_event_chain": "44dyfE5GawzwfbG7Nz5r-­?9SpeG",
        "last_event_date": "2015-­?03-­?22T00:50:17"
    },
    "meta": {
        "limit": 25,
        "next": "/api/event/v1/event/?limit=25&offset=25",
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "app": 5,
            "contact_id": 5,
            "creation_date": "2015-­?03-­?17T18:34:08",
            "data": "From: Template Sender, To: Receiver's Full Name , Subject: Template Subject",
            "email": "email@email.com",
            "event": "email_send",
            "event_chain": "44dyfE5GawzwfbG7Nz5r-­?9SpeG",
            "resource_uri": "/api/event/v1/event/1/"
        }
    ]
}

Due to the amount of possible events the result is always returned with paging with the last event data being developed in the field info.

To retrieve information from a chain of events that begins with an email being sent, make a request to the following endpoint:

Endpoint: http://yourdomain.ecentry.io/api/event/v1/event/chain/
Method: get
Authorization: Basic

Passing as parameter the uuid returned in the email sending. This is the uuid string identifier of the events. To receive the results of the chain of events in the example above, you would do the following call:

http://yourdomain.ecentry.io/api/event/v1/event/chain/44dyfE5GawzwfbG7Nz5r-9SpeG

and you would have as an answer the following result:

{
    "info":{
        "event_count": 2,
        "last_event": "email_open",
        "last_event_date": "2015-­?03-­?22T05:08:23"
    },
    "objects": [
        {
            "app": 5,
            "contact_id": 5,
            "creation_date": "2015-­?03-­?22T03:51:04",
            "data": "From: Template Sender, To: Full Name, Subject: Template Subject",
            "email": "email@email.com",
            "event": "email_send",
            "event_chain": "44dyfE5GawzwfbG7Nz5r-­?9SpeG",
            "resource_uri": "/api/event/v1/event/160/"
        },
        {
            "app": 5,
            "contact_id": 5,
            "creation_date": "2015-­?03-­?22T03:51:35",
            "data": "{
                'HTTP_USER_AGENT': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/600.3.18 (KHTML, like Gecko)',
                'HTTP_COOKIE': None,
                'REMOTE_ADDR': '127.0.0.1',
                'HTTP_ACCEPT_LANGUAGE': 'en--us',
                'HTTP_HOST': '127.0.0.1:7070',
                'PATH_INFO': '/open/',
                'QUERY_STRING': 'h=1.5.5.44dyfE5GawzwfbG7Nz5r-­?9SpeG.1.6ede1863',
                'REMOTE_HOST': None,
                'REQUEST_URI': '/open/?h=1.5.5.44dyfE5GawzwfbG7Nz5r-­?9SpeG.1.6ede1863'
            }",
            "email": "email@email.com",
            "event": "email_open",
            "event_chain": "44dyfE5GawzwfbG7Nz5r-­?9SpeG",
            "resource_uri": "/api/event/v1/event/161/"
        }
    ]
}

Note all resulting events from that sending will be returned in this call and without paging that the last event data is always available in the info field info.

Adding attachments

In order to send an email with a file attached add the tag attachments to your json, like in the example below:

{
    "to": {
        "name": "John Wayne",
        "email": "john.wayne@western.us",
    },
    "template": "SOME_TEMPLATE",
    "attachments": [
        {
            "name": "some_file.txt",
            "type": "text/plain",
            "content": "dHN0"
        },
        {
            "name": "another_file.txt",
            "type": "text/plain",
            "content": "dHN0"
        }
    ]
}

Notice that attachments is an array and its content must be in a Base64 codification.

It is also possible, in a single API call, to send different attachments to different contacts. You just need to do it like the following example:

{
    "to": [
        {
            "name": "John Snow",
            "email": "john.snow@western.us",
            "attachments": [{
                "name": "some_file.txt",
                "type": "text/plain",
                "content": "dHN0"
            }]
        },
        {
            "name": "Bruce Wayne",
            "email": "b.wayne@bol.com",
            "attachments": [{
                "name": "another_file.txt",
                "type": "text/plain",
                "content": "dHN0"
            }]
        }
    ],
    "template": "SOME_TEMPLATE"
}

API Libraries

Through our libraries you will be able to do a fast integration between Maildocker and your project with a variety of languages and frameworks. We keep the following official libraries for you to send your transactional emails:

maildocker-nodejs - Official NodeJS library
maildocker-php - Official PHP library
maildocker-python - Official Python library
maildocker-ruby - Official Ruby library

Code Examples

NodeJS

".. code:: javascript

    var md = require('maildocker')(api_user, api_password);

    md.send({
      to:       'john.snow@thrones.com',
      from:     'maildocker@ecentry.io',
      subject:  'maildocker-nodejs-library',
      text:     '**** ()'
    }, function(err, json) {
      if (err) { return console.error(err); }
      console.log(json);
    });

    // OR

    var message = new maildocker.Mail({
      subject:    'maildocker-nodejs-library',
      text:       '**** ()',
      merge_vars: {
        system: 'Maildocker', url: 'http://maildocker.io'
      }
    });
    message.addTo('john.snow@thrones.com', 'John Snow');
    message.setFrom('maildocker@ecentry.io', 'Maildocker');
    message.addAttachment({
      filename: 'spreadsheet.xls',
      content: new Buffer('You know nothing...')
    });

    md.send(message, function(err, json) {
      if (err) { return console.error(err); }
      console.log(json);
    });

PHP

.. code:: php

require_once "maildocker/Maildocker.php";

$md = new MaildockerClient('0cc175b9c0f1b6a831c', '92eb5ffee6ae2fec3ad');

$message = new Maildocker\Mail();

$message
    ->set_from('maildocker@ecentry.io', 'Maildocker')
    ->add_to('john.snow@thrones.com', 'John Snow')
    ->set_subject('maildocker-php-library')
    ->set_text('**** ()')
    ->add_vars(array('system' => 'Maildocker', 'url' => 'http://maildocker.io'))
    ->add_attachment(array(
        array('name' => 'plaintext.txt', 'type' => 'text/plain', 'content' => 'dHN0'),
        'spreadsheet.xls'
    ));

list($http_status, $response) = $md->send($message);

Python

.. code:: python

    import maildocker

    md = maildocker.MaildockerClient(
        api_key='0cc175b9c0f1b6a831c',
        api_secret='92eb5ffee6ae2fec3ad'
    )

    message = maildocker.Mail(
        mail_from='Maildocker ',
        to='John Snow ',
        subject='maildocker-python-library',
        text='**** ()',
        merge_vars={'system': 'Maildocker', 'url': 'http://maildocker.io'},
        attachments=[
            {'name': 'plaintext.txt', 'type': 'text/plain', 'content': 'dHN0'},
            'spreadsheet.xls'
        ]
    )

    http_status, response = md.send(message)

    # OR

    message = maildocker.Mail()

    message.set_from('Maildocker ')
    message.add_to('John Snow ')
    message.set_subject('maildocker-python-library')
    message.set_text('**** ()')
    message.add_vars({'system': 'Maildocker', 'url': 'http://maildocker.io'})
    message.add_attachment([
        {'name': 'plaintext.txt', 'type': 'text/plain', 'content': 'dHN0'},
        'spreadsheet.xls'
    ])

    http_status, response = md.send(message)

Ruby

.. code:: ruby

    require 'maildocker'

    md = Maildocker::Client.new(api_user: '0cc175b9c0f1b6a831c', api_key='92eb5ffee6ae2fec3ad')

    # OR

    md = Maildocker::Client.new do |c|
      c.api_user = '0cc175b9c0f1b6a831c'
      c.api_key = '92eb5ffee6ae2fec3ad'
    end

    # THEN

    mail = Maildocker::Mail.new do |m|
      m.add_to('john.snow@thrones.com', 'John Snow')
      m.set_from('maildocker@ecentry.io', 'Maildocker')
      m.subject = 'maildocker-ruby-library'
      m.text = '**** ()'
      m.add_attachment('spreadsheet.xls')
    end

    md.send(mail)

    # OR

    md.send(Maildocker::Mail.new(to: 'john.snow@thrones.com', from: 'maildocker@ecentry.io', subject: 'maildocker-ruby-library', text: '**** ()'))