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.
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>
<?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>
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.
Almost all CSS will be applied inline. There are two ways to force CSS rules
into style
tags in the document head:
scoped="scoped"
attribute to the style element. These
will be preserved as-is, although the scoped attribute will be
removed.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.
!important
do not workCSS 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.
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.
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 mobileYou must log in to use this resource.
Test a page that you are developing against this email.
5d23ebc126702 0.00 | - Batch 5d23ebc126702 0.00 | Started 2019-07-09 03:20 batch size: 200 end | time: 2019-07-09 03:24 5d23ebc126702 15.02 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ebc126702 30.03 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ebc126702 60.03 | Slept 30 5d23ebc126702 75.05 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ebc126702 90.07 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ebc126702 120.07 | Slept 30 5d23ebc126702 135.08 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ebc126702 150.10 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ebc126702 180.10 | Slept 30 5d23ebc126702 195.12 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ebc126702 210.13 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ebc126702 240.13 | Slept 30 5d23eced703c1 0.00 | - Batch 5d23eced703c1 0.00 | Started 2019-07-09 03:25 batch size: 200 end | time: 2019-07-09 03:29 5d23eced703c1 15.02 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23eced703c1 30.03 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23eced703c1 60.03 | Slept 30 5d23eced703c1 75.05 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23eced703c1 90.07 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23eced703c1 120.07 | Slept 30 5d23eced703c1 135.08 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23eced703c1 150.10 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23eced703c1 180.10 | Slept 30 5d23eced703c1 195.12 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23eced703c1 210.13 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23eced703c1 240.13 | Slept 30 5d23ee1985e3c 0.00 | - Batch 5d23ee1985e3c 0.00 | Started 2019-07-09 03:30 batch size: 200 end | time: 2019-07-09 03:34 5d23ee1985e3c 15.02 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ee1985e3c 30.03 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ee1985e3c 60.03 | Slept 30 5d23ee1985e3c 75.05 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ee1985e3c 90.07 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ee1985e3c 120.07 | Slept 30 5d23ee1985e3c 135.08 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ee1985e3c 150.10 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ee1985e3c 180.10 | Slept 30 5d23ee1985e3c 195.11 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ee1985e3c 210.13 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ee1985e3c 240.13 | Slept 30 5d23ef45e0097 0.00 | - Batch 5d23ef45e0097 0.00 | Started 2019-07-09 03:35 batch size: 200 end | time: 2019-07-09 03:39 5d23ef45e0097 15.02 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ef45e0097 30.03 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ef45e0097 60.03 | Slept 30 5d23ef45e0097 75.05 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ef45e0097 90.07 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ef45e0097 120.07 | Slept 30 5d23ef45e0097 135.08 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ef45e0097 150.10 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ef45e0097 180.10 | Slept 30 5d23ef45e0097 195.11 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ef45e0097 210.13 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23ef45e0097 240.13 | Slept 30 5d23f071295cf 0.00 | - Batch 5d23f071295cf 0.00 | Started 2019-07-09 03:40 batch size: 200 end | time: 2019-07-09 03:44 5d23f071295cf 15.02 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f071295cf 30.03 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f071295cf 60.03 | Slept 30 5d23f071295cf 75.05 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f071295cf 90.07 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f071295cf 120.07 | Slept 30 5d23f071295cf 135.08 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f071295cf 150.10 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f071295cf 180.10 | Slept 30 5d23f071295cf 195.12 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f071295cf 210.13 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f071295cf 240.13 | Slept 30 5d23f19d65cc7 0.00 | - Batch 5d23f19d65cc7 0.00 | Started 2019-07-09 03:45 batch size: 200 end | time: 2019-07-09 03:49 5d23f19d65cc7 15.02 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f19d65cc7 30.03 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f19d65cc7 60.03 | Slept 30 5d23f19d65cc7 75.05 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f19d65cc7 90.07 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f19d65cc7 120.07 | Slept 30 5d23f19d65cc7 135.08 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f19d65cc7 150.10 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f19d65cc7 180.10 | Slept 30 5d23f19d65cc7 195.12 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f19d65cc7 210.13 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f19d65cc7 240.13 | Slept 30 5d23f2c99b1d6 0.00 | - Batch 5d23f2c99b1d6 0.00 | Started 2019-07-09 03:50 batch size: 200 end | time: 2019-07-09 03:54 5d23f2c99b1d6 15.02 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f2c99b1d6 30.03 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f2c99b1d6 60.03 | Slept 30 5d23f2c99b1d6 75.05 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f2c99b1d6 90.07 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f2c99b1d6 120.07 | Slept 30 5d23f2c99b1d6 135.08 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f2c99b1d6 150.10 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f2c99b1d6 180.10 | Slept 30 5d23f2c99b1d6 195.11 | Sent 0 from | http://brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f2c99b1d6 210.13 | Sent 0 from | http://dev.brief.euractiv.eu/endpoints/outbox.php?api_key=Uj1chaib 5d23f2c99b1d6 240.13 | Slept 30
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 |