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

Email Message Builder API

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

Parameter	Type	Value
`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:

Key	Type	Value
`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>

Developing HTML Emails

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.

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

Send test email

You must log in to use this resource.

Test a page that you are developing against this email.

View Log Files

5d23f3f5a6983   0.00 |  - Batch
5d23f3f5a6983   0.00 | Started 2019-07-09 03:55 
 batch size: 200 
 end
                     | time: 2019-07-09 03:59
5d23f3f5a6983  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f3f5a6983  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f3f5a6983  60.03 | Slept 30
5d23f3f5a6983  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f3f5a6983  90.07 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f3f5a6983 120.07 | Slept 30
5d23f3f5a6983 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f3f5a6983 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f3f5a6983 180.10 | Slept 30
5d23f3f5a6983 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f3f5a6983 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f3f5a6983 240.13 | Slept 30
5d23f521d6305   0.00 |  - Batch
5d23f521d6305   0.00 | Started 2019-07-09 04:00 
 batch size: 200 
 end
                     | time: 2019-07-09 04:04
5d23f521d6305  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f521d6305  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f521d6305  60.03 | Slept 30
5d23f521d6305  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f521d6305  90.06 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f521d6305 120.06 | Slept 30
5d23f521d6305 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f521d6305 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f521d6305 180.10 | Slept 30
5d23f521d6305 195.11 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f521d6305 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f521d6305 240.13 | Slept 30
5d23f64d44d3e   0.00 |  - Batch
5d23f64d44d3e   0.00 | Started 2019-07-09 04:05 
 batch size: 200 
 end
                     | time: 2019-07-09 04:09
5d23f64d44d3e  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f64d44d3e  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f64d44d3e  60.03 | Slept 30
5d23f64d44d3e  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f64d44d3e  90.07 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f64d44d3e 120.07 | Slept 30
5d23f64d44d3e 135.09 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f64d44d3e 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f64d44d3e 180.10 | Slept 30
5d23f64d44d3e 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f64d44d3e 210.14 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f64d44d3e 240.14 | Slept 30
5d23f77990034   0.00 |  - Batch
5d23f77990034   0.00 | Started 2019-07-09 04:10 
 batch size: 200 
 end
                     | time: 2019-07-09 04:14
5d23f77990034  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f77990034  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f77990034  60.03 | Slept 30
5d23f77990034  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f77990034  90.07 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f77990034 120.07 | Slept 30
5d23f77990034 135.09 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f77990034 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f77990034 180.10 | Slept 30
5d23f77990034 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f77990034 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f77990034 240.13 | Slept 30
5d23f8a5b97df   0.00 |  - Batch
5d23f8a5b97df   0.00 | Started 2019-07-09 04:15 
 batch size: 200 
 end
                     | time: 2019-07-09 04:19
5d23f8a5b97df  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f8a5b97df  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f8a5b97df  60.03 | Slept 30
5d23f8a5b97df  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f8a5b97df  90.07 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f8a5b97df 120.07 | Slept 30
5d23f8a5b97df 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f8a5b97df 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f8a5b97df 180.10 | Slept 30
5d23f8a5b97df 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f8a5b97df 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f8a5b97df 240.13 | Slept 30
5d23f9d15b114   0.00 |  - Batch
5d23f9d15b114   0.00 | Started 2019-07-09 04:20 
 batch size: 200 
 end
                     | time: 2019-07-09 04:24
5d23f9d15b114  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f9d15b114  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f9d15b114  60.04 | Slept 30
5d23f9d15b114  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f9d15b114  90.07 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f9d15b114 120.07 | Slept 30
5d23f9d15b114 135.09 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f9d15b114 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f9d15b114 180.10 | Slept 30
5d23f9d15b114 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f9d15b114 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23f9d15b114 240.13 | Slept 30
5d23fafd34fca   0.00 |  - Batch
5d23fafd34fca   0.00 | Started 2019-07-09 04:25 
 batch size: 200 
 end
                     | time: 2019-07-09 04:29
5d23fafd34fca  15.02 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23fafd34fca  30.03 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23fafd34fca  60.03 | Slept 30
5d23fafd34fca  75.05 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23fafd34fca  90.07 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23fafd34fca 120.07 | Slept 30
5d23fafd34fca 135.08 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23fafd34fca 150.10 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23fafd34fca 180.10 | Slept 30
5d23fafd34fca 195.12 | Sent 0 from
                     | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23fafd34fca 210.13 | Sent 0 from
                     | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib
5d23fafd34fca 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:

Name	Type	Description	Current Setting
`email_tools_test_address`	string	Send test emails here	Login to view this setting
`email_tools_process_limit`	integer	Number of seconds the processing service should run before shutting down	240
`email_tools_pull_urls`	array	URLs to pull emails from	Login to view this setting
`callmap_driver`	string	The callmap driver to use, either "sqlite", "fsstore" or "noop"	noop
`callmap_labels`	array	Labels for the callmap, where the key is the regular expression to match and the value is the label to use	Login to view this setting
`callmap_visualize_default`	array	Nodes to visualize by default	Login to view this setting
`callmap_probability`	integer	Probability that a given hit will log. Important for high traffic sites. Set higher for lower probability.	1000
`http_allowed_domains`	array	Allowed domains for fetching assets or generating URLs	Login to view this setting
`http_allowed_urls`	array	Specified URLs or regular expressions of specified URLs match for fetching assets or generating URLs	Login to view this setting
`http_connect_timeout`	integer	The amount of time, in seconds, that cURL should wait before returning an error status. 15 is a good value for most cases.	15
`api_key`	string	The 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_driver`	string	The emailer driver to use	Login to view this setting
`emailer_batch_size`	integer	The 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 value	Login to view this setting
`emailer_cooloff`	integer	The time (in seconds) to wait between sending batches. This is to allow you to stay within service provider throttles	Login to view this setting
`emailer_default_from_name`	string	The default "from" name	Login to view this setting
`emailer_default_from_addr`	string	The default "from" address	Login to view this setting
`emailer_default_reply_to`	string	The default "reply to" address	Login to view this setting
`emailer_mandrill_path`	string	Path to the Mandrill PHP library	Login to view this setting
`emailer_mandrill_api_key`	string	Your Mandrill API Key	Login to view this setting
`log_per_file`	integer	The number of entries to keep in a log file before rotating it	100
`log_keep_files`	integer	The number of log files to keep before deleting	10
`shortener_driver`	string	The driver for the shortener, can be one of "bitly", "eurac" or "noshorten"	eurac
`shortener_base_url`	string	The base URL for the shortener	http://eurac.tv
`shortener_api_key`	string	The API key for the shortener	Login to view this setting
`shortener_passthru_query_vars`	array	Query 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