Code Block |
---|
language | php |
---|
theme | RDark |
---|
title | PHP - Sending transactional emails using SMTP+ |
---|
linenumbers | true |
---|
|
<?php
//########################################################
//Include the PHPmailer class.
//
//PHPmailer allows you to create and transport an email an email message.
//The PHPmailer class is available at this address:
//https://github.com/PHPMailer/PHPMailer/
//########################################################
require_once "class.phpmailer.php";
$EmailMessage = new PHPmailer();
$EmailMessage->SetLanguage('en','language/'); //Define the language
//**********************************************
//SMTP configuration
//**********************************************
$EmailMessage->IsSMTP(); //Specify usage of SMTP Server
$EmailMessage->Host = "infast.smtpok.com"; //SMTP+ Server address
$EmailMessage->Port="25"; //SET the SMTP Server port
$EmailMessage->Username = "smtpplus_username"; //SMTP+ authentication: username
$EmailMessage->Password = "smtpplus_password"; //SMTP+ authentication: password
$EmailMessage->SMTPAuth = true; //Authentication required
//**********************************************
//Email data
//**********************************************
$EmailMessage->IsHTML(true); //Set the email format
$EmailMessage->FromName= "myname"; //From: display name
$EmailMessage->From="sender_address@domain.com"; //From: email address
$EmailMessage->AddAddress("recipient_address@domail.com"); //Add one or more recipients
$EmailMessage->Subject="My first email sent via SMTP+"; //Set the email subject
$EmailMessage->Body="<b>Hello,<b><br/>This is my first email."; //Set the email body
$EmailMessage->AltBody="Hello, This is my first email.."; //Set the email text part
//**********************************************
//Send the email
//**********************************************
if(!$EmailMessage->Send())
{
echo "<h1>Error sending the email.</h1>"; //Email was not sent
}
else
{
echo "Email has been sent"; //Mail sent
}
?> |
SMTP+
v2:
new advanced features and sample code
The new version of our SMTP relay service provides new features and improved performance.
Host domains
During the beta testing period of our SMTP+ service we added a new host domain (fast.smtpok.com) for those who were interested in trying the new features in advance.
Now both the following host names provide exactly the same result:
- in.smtpok.com (as suggested on MailUp admin console when creating a new SMTP+ user)
- fast.smtpok.com
New features
The new version of our Host domains
for your transactional sending application you must set:
- fast.smtpok.com (as suggested on MailUp admin console when creating a new SMTP+ user)
Code Block |
---|
|
$EmailMessage->Host = "fast.smtpok.com"; //SMTP+ Server address |
Advanced settings
Our SMTP relay service supports a X-SMTPAPI custom header that allows you to access several new features several features by specifying additional parameters through a JSON object.
Expand |
---|
title | Click here to learn more about X-SMTPAPI data format |
---|
|
The following table includes the parameters that can be added through X-SMTPAPI to override the settings that are defined at the MailUp list or at the SMTP+ user level. None of these fields is mandatory. X-SMTPAPI value is processed by MailUp but it is not actually added to the headers of the delivered message. Field name | Description |
---|
CampaignName | String that is displayed as aggregate message name on admin console |
---|
CampaignCode | String that is used for message aggregation,overrides list settings. When not specified, MailUp applies the aggregation type of used SMTP+ account |
---|
Header | Boolean, overrides the list settings about adding default header or not. |
---|
Footer | Boolean, overrides the list settings about adding default footer or not. |
---|
ClickTracking | Boolean, overrides the list settings about click tracking. |
---|
ViewTracking | Boolean, overrides the list settings about open tracking. |
---|
Priority | Integer, from 1 (highest) to 5 (lowest), overrides SMTP+ account settings |
---|
Schedule | Used to schedule send. An example of expected format is "2015-02-26T15:55+02:00". Send is immediate if field is equal to "null" or specifies a date-time that occurs in the past |
---|
DynamicFields | Array of key-value pairs to be used as merge tags ("N" = name or key, "V" = value) |
---|
SkipDynamicFields | When this field is set to "true", placeholders (i.e. text between square brackets) are not managed as merge tags. Example: No Format |
---|
| SkipDynamicFields= true -> [ |
|
---|
emailname] is not replaced by the recipient's |
| email addressname.
SkipDynamicFields= false, null or not specified -> [ |
| emailname] is replaced by the recipient's |
| email address. Code Block |
---|
|
|
{
"Please note that MailUp specific tags like [email] and [idoptin] cannot be skipped, hence the "SkipDynamicFields= true" setting does not apply to them. |
Code Block |
---|
|
{
"CampaignName":"myCampaign",
"CampaignCode":"Code001",
"Header":false,
"Footer":true,
"ClickTracking":true,
"ViewTracking":true,
"Priority":1,
"Schedule":null,
"DynamicFields":[{"N":"itemid","V":"ABC-1234"},{"N":"description","V":"Womens Regular and Wide-Calf Knee-High Studded Riding Boot"},{"N":"price","V":"$149.99"}],
"SkipDynamicFields":null
} |
Go faster
The new version of SMTP+ provides a substantial increase in performance.
As mentioned above, you simply need to change the domain to fast.smtpok.com from in.smtpok.com to experience the increase in performance.
Code Block |
---|
|
// switching to fast.smtpok.com leads to a substantial reduction in latency
$EmailMessage->Host = "fast.smtpok.com"; //SMTP+ Server address :"description","V":"Womens Regular and Wide-Calf Knee-High Studded Riding Boot"},{"N":"price","V":"$149.99"}],
"SkipDynamicFields":null
} |
|
Among the various new important features, SMTP+ v2 supports merge tags (also called dynamic fields in MailUp).
You can use two kinds of merge tags:
- merging values defined in recipient fields
- merging values defined in the header of the message
In both cases, the syntax to be used in the message code is:
- name of the tag in lowercase
- between square brackets
For example, if you created a custom recipient field in your MailUp account called FirstName, the merge tag to use in the subject or body of the email message would be:
You can merge tags for any of those recipient fields. Substitution occurs at the time the message is sentissent, when those fields contain a value. Otherwise empty values will be displayed in place of the placeholder.
Code Block |
---|
|
// Merge tags are replaced at sending time by empty values when no value is found for the recipient.
// No action occurs when the merge tag does not correspond to a personal data field.
$EmailMessage->Subject="Hello [firstname]: your order has been shipped!";
$EmailMessage->Body="Hello [firstname],<br /><br />we thought you'd like to know that order [latestorderid] was <strong>shipped on [latestshippedorderdate]</strong>.<br /><br />Thanks again for visiting our online store!"; |
With SMTP+ v2 you you can reuse a message template (i.e. the same subject and body) and customize it with key-value pairs that are specified through custom headers added to the message. Also tables and HTML content can be used as a merge tag's value.
Code Block |
---|
|
// Placeholder are replaced at sending time by empty values when no value was previously added for the recipient.
// No action occurs when the specified placeholder does not correspond to a personal data field for that account.
$EmailMessage->Subject="Recommended books for [customername]"; //Set the email subject
$EmailMessage->Body="<b>Hello [customername], we recommend you [title1] by [author1]. Buy now at [price1].<b><br/> Please find enclosed your invoice <b><br/>. Kind regards"; //Set the email body
$EmailMessage->AddCustomHeader("X-SMTPAPI: {\"DynamicFields\":[{\"N\":\"customername\",\"V\":\"John\"},{\"N\":\"title1\",\"V\":\"Become an email guru\"},{\"N\":\"price1\",\"V\":\"$10.99\"},{\"N\":\"author1\",\"V\":\"Martha G.\"}]}"); |
Custom reports based on campaign code
In order to create meaningful statistics for transactional mailings, MailUp aggregates sending data based on a variety of parameters. For example, you can instruct the system to aggregate by message subject, or SMTP+ user, etc.
SMTP+ v2 introduces introduces the ability to aggregate sending data based on a custom CampaignCode parameter. This allows you to create a customized aggregation when none of the available options suits the desired behavior.
For example, let's say that you wanted to aggregate sending statistics based on a specific keyword that is inside the message subject: there would be no way to meet your needs with the predefined aggregation options that are available in the SMTP+ settings within the MailUp admin console.
The CampaignCode parameter comes to the rescue, allowing you to specify a code within the message header and force aggregation based on that code.
An additional parameter called CampaignName can be used to specify a name to be displayed on inside the MailUp admin console for those.
Code Block |
---|
|
// All the emails with CampaignCode = "Code001" will be treated as different sending of the same message
// Message name ("subject" field) on admin console is set by the CampaignName of the first call with CampaignCode = "Code001". CampaignName of further calls with the same Campaign code is ignored.
$EmailMessage->AddCustomHeader("X-SMTPAPI: {\"CampaignName\":\"Custom Aggregation 001\",\"CampaignCode\":\"Code001\"}"); |
Message scheduling
Another important feature added with SMTP+ v2 is is support deferred sending. Specifically, you can now schedule a message so that it is sent at a specified date and time (with time zone).
Note: the message is sent immediately when the specified date and time has already occurred.
Code Block |
---|
|
// Schedule sending on Feb 26th 2015 at 15:55 UTC+2
$EmailMessage->AddCustomHeader("X-SMTPAPI: {\"Schedule\":\"2015-02-26T15:55+02:00\"}"); |
Use commas as the separator for the X-SMTPAPI parameters that you wish to set in the message header.
Code Block |
---|
|
// Schedule sending + Set Campaign Name & code
$EmailMessage->AddCustomHeader("X-SMTPAPI: {\"CampaignName\":\"Custom Aggregation 001\",\"CampaignCode\":\"Code001\",\"Schedule\":\"2015-02-26T15:55+02:00\"}"); |