Email Tools


This plugin provides a set of tools for transforming working with email. The goal is to abstract the difficulties away from other web development techniques.

Documentation and Examples


The HTML to Email method takes HTML input and transforms it so that it is save to send as an HTML body. It will generate both a rich text body and an alternate text body.

//assets.euractiv.com/email-tools/builder.php
ParameterTypeValue
api_key string The server-to-server API key.
source URL The HTML to process.
max_image_width integer If set, will embed images in the email message instead of simply rebasing them to point to the original source. Images wider than this number will be resized down.
content_selector CSS or XPath selector Complex webpages often have a lot of stuff you don't want to send in the email. If this selector is set, it will extract only that content for building the email. Optional, default //body
template URL The email template to inject content into. This setting is optional; by default it uses a variant of the popular Email Boilerplate template, which should be OK for most applications.
template_selector CSS or XPath selector If using a custom template, the selector to inject the content into. Defaults to //body.
format html or text For debugging, return only the format requested as a webpage.

NOTE: The API can result in very long query strings in your URLs. Therefore, you may experience failures if you are sending data as raw HTML. For this reason, the endpoint will accept both GET requests with the data in the query or POST requests with the data in the request body.

The API will return a JSON object with two offsets:

KeyTypeValue
html string The HTML body of the email
text string The alternate text body.
error string If there was a fatal processing error, it will be stored here. It will be an empty string if there was no error.
warnings array Non-fatal processing errors
transformations array A list of transformations made. Useful for debugging.
<?php

$url = 'https://assets.euractiv.com/email-tools/builder.php?' . http_build_query(array (
  'api_key' => '-private-',
  'source' => 'https://assets.euractiv.com/email-tools/examples/01-builder/email.html',
));
$result = json_decode(file_get_contents($url), true);

$result now contains:

''
<pre>
&lt;?php

$url = 'https://assets.euractiv.com/email-tools/builder.php?' . http_build_query(array (
  'api_key' => '-private-',
  'source' => 'https://assets.euractiv.com/email-tools/examples/01-builder/email.html',
));
$result = json_decode(file_get_contents($url), true);

</pre>
<p><code>$result</code> now contains:</p>
<pre>''</pre>



Test a page in development


To see what a page you are working on will look like when converted to EMail html, upload it online somewhere and enter the URL below. The app will download and format it, and show you how it displays.

Log in to use the email template tester function.


Limitations and quirks


Inline vs Head styles

Almost all CSS will be applied inline. There are two ways to force CSS rules into style tags in the document head:

  • Add a scoped="scoped" attribute to the style element. These will be preserved as-is, although the scoped attribute will be removed.
  • Wrap the ruleset in a media query. All media queries will be preserved in the document head.

Padding.

Padding does not work reliably in email. If this tool finds any padding declarations, it will be added to the element's margin. To implement pseudo-padding, you need to add a wrapper element and apply the padding to the inner element as margin.


CSS Specificity and !important do not work

CSS rules will be appied in the order they are encountered, not by specificity. For example, consider this ruleset:

.white {background-color: white;}
div {background-color: grey;}

In a browser, an element div.white would have a white background. In this tool, it will have grey background. In practice, this limitation does not cause too many problems since CSS is usually written more or less in order of specificity, but it can be a source of unexpected results.


Table cell margin/padding.

Padding and margin on table cells (td) does not work reliably in email. Cell padding should be set with the cellpadding attribute on the parent table. As a convenience, the application understands a non-standard border-padding css property on tables that will be converted to cellpadding.


Media queries and device targetting

Many devices can be targetted with media queries. Some useful queries include:

/* generic mobile */
@media only screen and (max-device-width: 480px) {}

/* tablets */
@media only screen and (min-device-width: 768px) and (max-device-width: 1024px) {}

/* High density (hdpi) iPhones with retina display */
@media only screen and (-webkit-min-device-pixel-ratio: 2) {}

/* High density (hdpi) android */
@media only screen and (-webkit-device-pixel-ratio:1.5){}

/* Medium density (mdpi) android */
@media only screen and (-webkit-device-pixel-ratio:1){}

/* Low density (ldpi) android */
@media only screen and (-webkit-device-pixel-ratio:.75){}

Targetting Outlook and IE mobile can be done with conditional comments, which will be preserved as-is in the resulting email. A conditional comment would look like:

<--[if {expression}]>
    <style type="text/css">
        /* MS-specific styles here */
    </style>
<![endif]-->

Some useful expressions:

  • [if gte mso 9]: Outlook 2000 and above
  • [if (gte mso 9)&(lte mso 11)]: Outlook 2000-2003, using the IE6 rendering engine.
  • [if (gte mso 12)&(lte mso 15)]: Outlook 2007 and above, using the Microsoft Word rendering engine.
  • [if mso 16]: Outlook 2016 and the mail reader app on Windows Phone 8 and 10.
  • [if IEMobile 7]: Older windows mobile

You must log in to use this resource.

Test a page that you are developing against this email.


View Log Files

5d23e38d86cd5   0.00 |  - Batch
5d23e38d86cd5   0.00 | Started 2019-07-09 02:45 
 batch size: 200 
 end
                     | time: 2019-07-09 02:49
5d23e38d86cd5  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e38d86cd5  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e38d86cd5  60.03 | Slept 30
5d23e38d86cd5  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e38d86cd5  90.06 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e38d86cd5 120.06 | Slept 30
5d23e38d86cd5 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e38d86cd5 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e38d86cd5 180.10 | Slept 30
5d23e38d86cd5 195.11 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e38d86cd5 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e38d86cd5 240.13 | Slept 30
5d23e4b963db4   0.00 |  - Batch
5d23e4b963db4   0.00 | Started 2019-07-09 02:50 
 batch size: 200 
 end
                     | time: 2019-07-09 02:54
5d23e4b963db4  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e4b963db4  30.04 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e4b963db4  60.04 | Slept 30
5d23e4b963db4  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e4b963db4  90.06 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e4b963db4 120.06 | Slept 30
5d23e4b963db4 135.07 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e4b963db4 150.09 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e4b963db4 180.09 | Slept 30
5d23e4b963db4 195.11 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e4b963db4 210.12 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e4b963db4 240.13 | Slept 30
5d23e5e55824a   0.00 |  - Batch
5d23e5e55824a   0.00 | Started 2019-07-09 02:55 
 batch size: 200 
 end
                     | time: 2019-07-09 02:59
5d23e5e55824a  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e5e55824a  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e5e55824a  60.03 | Slept 30
5d23e5e55824a  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e5e55824a  90.06 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e5e55824a 120.06 | Slept 30
5d23e5e55824a 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e5e55824a 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e5e55824a 180.10 | Slept 30
5d23e5e55824a 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e5e55824a 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e5e55824a 240.13 | Slept 30
5d23e71164045   0.00 |  - Batch
5d23e71164045   0.00 | Started 2019-07-09 03:00 
 batch size: 200 
 end
                     | time: 2019-07-09 03:04
5d23e71164045  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e71164045  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e71164045  60.03 | Slept 30
5d23e71164045  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e71164045  90.06 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e71164045 120.06 | Slept 30
5d23e71164045 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e71164045 150.09 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e71164045 180.10 | Slept 30
5d23e71164045 195.11 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e71164045 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e71164045 240.13 | Slept 30
5d23e83d61b84   0.00 |  - Batch
5d23e83d61b84   0.00 | Started 2019-07-09 03:05 
 batch size: 200 
 end
                     | time: 2019-07-09 03:09
5d23e83d61b84  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e83d61b84  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e83d61b84  60.03 | Slept 30
5d23e83d61b84  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e83d61b84  90.07 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e83d61b84 120.07 | Slept 30
5d23e83d61b84 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e83d61b84 150.11 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e83d61b84 180.11 | Slept 30
5d23e83d61b84 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e83d61b84 210.14 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e83d61b84 240.14 | Slept 30
5d23e969320ea   0.00 |  - Batch
5d23e969320ea   0.00 | Started 2019-07-09 03:10 
 batch size: 200 
 end
                     | time: 2019-07-09 03:14
5d23e969320ea  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e969320ea  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e969320ea  60.03 | Slept 30
5d23e969320ea  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e969320ea  90.07 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e969320ea 120.07 | Slept 30
5d23e969320ea 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e969320ea 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e969320ea 180.10 | Slept 30
5d23e969320ea 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e969320ea 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23e969320ea 240.13 | Slept 30
5d23ea9563dc6   0.00 |  - Batch
5d23ea9563dc6   0.00 | Started 2019-07-09 03:15 
 batch size: 200 
 end
                     | time: 2019-07-09 03:19
5d23ea9563dc6  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23ea9563dc6  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23ea9563dc6  60.03 | Slept 30
5d23ea9563dc6  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23ea9563dc6  90.07 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23ea9563dc6 120.07 | Slept 30
5d23ea9563dc6 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23ea9563dc6 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23ea9563dc6 180.10 | Slept 30
5d23ea9563dc6 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23ea9563dc6 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23ea9563dc6 240.13 | Slept 30

Configuration

Configuration is located in the file /config/email-tools.php. If you do not have the ability to modify this file, contact your administrator to have options changed. The configuration file should contain an array with the name $config containing the following offsets:

NameTypeDescriptionCurrent Setting
email_tools_test_addressstringSend test emails hereLogin to view this setting
email_tools_process_limitintegerNumber of seconds the processing service should run before shutting down
240
email_tools_pull_urlsarrayURLs to pull emails fromLogin to view this setting
callmap_driverstringThe callmap driver to use, either "sqlite", "fsstore" or "noop"
noop
callmap_labelsarrayLabels for the callmap, where the key is the regular expression to match and the value is the label to useLogin to view this setting
callmap_visualize_defaultarrayNodes to visualize by defaultLogin to view this setting
callmap_probabilityintegerProbability that a given hit will log. Important for high traffic sites. Set higher for lower probability.
1000
http_allowed_domainsarrayAllowed domains for fetching assets or generating URLsLogin to view this setting
http_allowed_urlsarraySpecified URLs or regular expressions of specified URLs match for fetching assets or generating URLsLogin to view this setting
http_connect_timeoutintegerThe amount of time, in seconds, that cURL should wait before returning an error status. 15 is a good value for most cases.
15
api_keystringThe key to access protected API calls. This key should only be used in server-to-server communication to avoid exposing it to the broader internet. In requests, the key can be set in the query as the "api_key" value (eg http://example.com?api_key=keyboard_cat), in a POST request body as the "api_key" value, or as a header with the name "X-Vsac-Api-Key".Login to view this setting
emailer_driverstringThe emailer driver to useLogin to view this setting
emailer_batch_sizeintegerThe size of batches to send emails in. Depending on the service provider, you may be able to send larger or smaller requests. The bigger your emails (esp number of attachments), the smaller this number should be. 200 is usually a good valueLogin to view this setting
emailer_cooloffintegerThe time (in seconds) to wait between sending batches. This is to allow you to stay within service provider throttlesLogin to view this setting
emailer_default_from_namestringThe default "from" nameLogin to view this setting
emailer_default_from_addrstringThe default "from" addressLogin to view this setting
emailer_default_reply_tostringThe default "reply to" addressLogin to view this setting
emailer_mandrill_pathstringPath to the Mandrill PHP libraryLogin to view this setting
emailer_mandrill_api_keystringYour Mandrill API KeyLogin to view this setting
log_per_fileintegerThe number of entries to keep in a log file before rotating it
100
log_keep_filesintegerThe number of log files to keep before deleting
10
shortener_driverstringThe driver for the shortener, can be one of "bitly", "eurac" or "noshorten"
eurac
shortener_base_urlstringThe base URL for the shortener
http://eurac.tv
shortener_api_keystringThe API key for the shortenerLogin to view this setting
shortener_passthru_query_varsarrayQuery variables to leave in the URL, for example to prevent the creation of millions of URLs with unique ids, or to prevent sensitive information from being saved in the shortener.Login to view this setting