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:

  • to - Email recipients*
  • name - Recipient name
  • email - Contact's email address*
  • merge_vards - Personalization variables
  • attachment - Email attachment
  • from - Sender's email address
  • subject - Email's subject line
  • text - Text/plain version of the email content
  • html - Text/html version of the email content
  • template - Name of a email template created on Maildocker (loads from, subject, text and html)
  • tracking_domain - Domain used for tracking, that must be registered and authenticated on Maildocker
  • return_path_domain - Return-path domain, that must be registered and authenticated on Maildocker
  • html_click_tracking (boolean) - Enables or disables link tracking in the HTML version of email
  • text_click_tracking (boolean) - Enables or disables link tracking in the text version of email
  • open_tracking - (boolean) - Enables or disables open tracking in the HTML version of email
  • unsubscribe_tracking (boolean) - Enables or disables the Unsubscribe link in the email
  • enable_list_unsubscribe (boolean) - Enables or disables list Unsubscribe in case a default list is enabled in the Docklet
  • show_unsubscribe_lists (boolean) - Shows all lists the contact is currently in when unsubscribing, for selection
  • bcc_to - Add hidden recipients
  • auto_text (boolean) - Generates a text version from the HTML version of the content
  • auto_html (boolean) - Generates a HTML version from the text version of the content (using Markdown)
  • preserve_recipients (boolean) - Maintain recipients in all messages, showing to contacts to all recipients
  • add_vcard (boolean) - Adds a attached VCARD with contact information from sender in sent emails
  • add_custom_footer (boolean) - Enables or disables personalized footer (set up in Docklet)
  • sandbox_to - Rewrites final recipient for sending emails on Sandbox mode, for testing purposes
  • enable_dkim (boolean) - Enables or disables email's digital signature (DKIM/DomainKeys)

*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> Job Title: \{\{job_title\}\}<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://api.maildocker.io/v1/mail/
Method: POST
Authorization: Basic
Content-Type: application / json

{ "template": "Maildocker Template", "to": { "name": "John Wayne", "email": "[email protected]" "merge_vars": { "job_title": "CEO" } } } 

Here is the same example sent by Curl

"curl -­?v -­?-­?user 933ff2214029fffe19c:8107ff48ff6bc4fb19 http://api.maildocker.io/v1/mail/ -­?H "Content-­?Type: application/json" -­?d {"to": [{ "name":"John Wayne", "email":"[email protected]", "merge_vars": {"job_title":"CEO"} }] }

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

...

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