uProduce Email Plug-in SDK

Introduction

The XMPie uProduce server, when licensed for cross media features, can serve as a production hub for transactional and marketing or bulk email messaging as part of a campaign designed and executed in Circle.

Out-of-the-box uProduce provides three delivery providers which are used for distribution of the composed email messages: Prepare for email distribution; SMTP Server; and XMPie Email Service (XES).

If required, it is possible to extend uProduce by developing delivery providers that integrate with other email services for the final delivery of the messages.

The SDK describes the implementation of the XMPie Email Plug-in sample. The sample demonstrates the creation of a custom XMPie Email plug-in and how to add it to the delivery providers displayed in the uProduce dashboard, which are also made available to Circle. In addition, there is a possibility to add the Tracking functionality which is also described in the SDK.

Note: This documentation reflects the updated uProduce Email Plugin SDK available for uProduce versions 26.1.1 and later.

Plug-in types

uProduce allows you to implement two types of email plug-ins: Template and Composed. The Template mode assumes that the delivery provider knows how to compose the email based on a template and a list of recipients with the ADOR or content object values.

For example:

Template

Copy 
<body>
  <p>
    Dear {{FIRST_NAME}} {{LAST_NAME}},
  </p>
  <p>
    Visit our website to register to the Open House event.
  </p>
</body>

Dynamic Objects

Name

Value

FIRST_NAME

John

LAST_NAME

Miller

EMAIL

John.Miller@gmail.com

Note: If the email document type in uProduce is ‘URL’, then the template will contain HTML_BODY and TEXT_BODY ADORs which represents the entire composed message body.

Composed

When using the Composed mode, the delivery provider receives the already composed email and must only implement the sending operation:

Copy 
<body>
  <p>
    Dear John Miller,
  </p>
  <p>
    Visit our website to register to the Open House event.
  </p>
</body>

To each one of the email plug-ins, whether Template or Composed, you can add the email tracking functionality using the Tracking add-on (see Tracking).

Accessing the SDK

XMPie provides the uProduce Email Plug-in SDK that includes a sample Visual Studio solution that demonstrates how to create a custom Email Delivery Provider.

Customers who have purchased the uProduce API license can request the uProduce Email Plug-in SDK from XMPie Support.

SDK setup

To work with the email plug-in sample, you will need Microsoft Visual Studio installed on a uProduce Development Server.

Unzip the uProduce Email Plugin SDK.zip to a desired location and open the solution.

Composed mode

Composed User Control Implementation

The user control provides the configuration interface displayed in the uProduce Dashboard when administrators set up your delivery provider: (Settings > Delivery Providers > New) and (Settings > Delivery Providers > Edit).

The EmailComposedPluginSample provided in the SDK includes a folder named DashboardConfig that includes the sample User Control EmailComposedSampleUI.ascx.

User Control (.ascx)

The .ascx file defines the form layout. The sample demonstrates separate fields for Server, Port, Username, and Password in a table layout that matches other dashboard delivery provider forms:

Copy 
<%@ Control Language="C#" AutoEventWireup="true"
    CodeFile="EmailComposedSampleUI.ascx.cs"
    Inherits="EmailComposedSampleUI" %>

<table class="delivery-provider-settings">
    <tr>
        <td><asp:Label ID="LabelServer" runat="server" Text="SMTP Server:"></asp:Label></td>
        <td><asp:TextBox ID="TextBoxServer" runat="server" Width="250px"></asp:TextBox></td>
    </tr>
    <tr>
        <td><asp:Label ID="LabelPort" runat="server" Text="Port:"></asp:Label></td>
        <td><asp:TextBox ID="TextBoxPort" runat="server" Width="80px"></asp:TextBox></td>
    </tr>
    <tr>
        <td><asp:Label ID="LabelUsername" runat="server" Text="Username:"></asp:Label></td>
        <td><asp:TextBox ID="TextBoxUsername" runat="server" Width="250px"></asp:TextBox></td>
    </tr>
    <tr>
        <td><asp:Label ID="LabelPassword" runat="server" Text="Password:"></asp:Label></td>
        <td><asp:TextBox ID="TextBoxPassword" runat="server" Width="250px" TextMode="Password"></asp:TextBox></td>
    </tr>
</table>

IDeliveryProviderTypeControl Implementation

The code-behind EmailComposedSampleUI.ascx.cs implements XMPieDashboard.IDeliveryProviderTypeControl, which extends the base IEmailProviderUserControl interface.

Note: IEmailProviderUserControl is the base interface and is still valid. However, plugins should implement the extended IDeliveryProviderTypeControl interface for full functionality including password encryption support.

Key aspects of the implementation:

  • The control implements XMPieDashboard.IDeliveryProviderTypeControl

  • DeliveryProviderParams is a typed array of EmailProviderParameter — one entry per setting (Server, Port, Username, Password)

  • PopulateControlValues() loads stored parameters by name via a switch on m_Name

  • SaveControlValues(bool inEncryptRelevantDetails) builds the parameter array. When inEncryptRelevantDetails is true, sensitive fields are wrapped with GeneralUtils.MarkForEncription so the framework persists them encrypted

  • Passwords are never echoed back; the form shows a mask and preserves the stored value if the user does not retype

Copy 
using System;
using System.Collections.Generic;
using System.Web.UI;
using EmailProviderExInterface;
using XMPieDashboard;

public partial class EmailComposedSampleUI : System.Web.UI.UserControl, IDeliveryProviderTypeControl
{
    private const string scPasswordMask = "******";

    public string DeliveryProviderID
    {
        get { return (string)ViewState["DeliveryProviderID"]; }
        set { ViewState["DeliveryProviderID"] = value; }
    }

    public string Name
    {
        get { return (string)ViewState["Name"]; }
        set { ViewState["Name"] = value; }
    }

    public int TypeID
    {
        get { return (int)ViewState["TypeID"]; }
        set { ViewState["TypeID"] = value; }
    }

    public bool SupportTest
    {
        get { return ViewState["SupportTest"] != null && (bool)ViewState["SupportTest"]; }
        set { ViewState["SupportTest"] = value; }
    }

    public XMPieWSAPIProxy.EmailProviderParameter[] DeliveryProviderParams
    {
        get { return (XMPieWSAPIProxy.EmailProviderParameter[])ViewState["DeliveryProviderParams"]; }
        set { ViewState["DeliveryProviderParams"] = value; }
    }

    // Legacy interface property - retained because IDeliveryProviderTypeControl
    // extends IEmailProviderUserControl. Not used by the modern path.
    public string DeliveryProviderParameters { get; set; }

    public string InitControls() { return null; }

    public void PopulateControlValues()
    {
        if (DeliveryProviderID == "-1" || string.IsNullOrEmpty(DeliveryProviderID))
        {
            // New provider - show defaults.
            PortTextBox.Text = "25";
            SupportTest = true;
            return;
        }

        DeliveryProvider deliveryProvider = DeliveryProvider.Get(DeliveryProviderID);
        Name = deliveryProvider.Name;
        DeliveryProviderParams = DeliveryProvider.GetDeliveryProviderParameters(DeliveryProviderID);

        foreach (var p in DeliveryProviderParams)
        {
            switch (p.m_Name)
            {
                case "Server":   ServerTextBox.Text   = p.m_Value; break;
                case "Port":     PortTextBox.Text     = p.m_Value; break;
                case "Username": UsernameTextBox.Text = p.m_Value; break;
                case "Password":
                    // Never echo the stored (encrypted) password back to the form.
                    // Show a mask so the user can tell something is stored; on save
                    // we'll preserve the existing value unless they typed a new one.
                    if (!string.IsNullOrEmpty(p.m_Value))
                        PasswordTextBox.Attributes.Add("value", scPasswordMask);
                    break;
            }
        }

        SupportTest = true;
    }

    // Modern save: build a structured EmailProviderParameter[] with one entry per
    // setting. The framework persists each as a separate 
    // element in the stored XML.
    public void SaveControlValues(bool inEncryptRelevantDetails)
    {
        Name = ((System.Web.UI.WebControls.TextBox)FindControl("ServerTextBox") != null) ? Name : Name;

        var list = new List
        {
            MakeParam("Server",   ServerTextBox.Text),
            MakeParam("Port",     PortTextBox.Text),
            MakeParam("Username", UsernameTextBox.Text),
            MakePasswordParam(inEncryptRelevantDetails),
        };

        DeliveryProviderParams = list.ToArray();
    }

    // Legacy interface method - the framework's edit page only calls this overload
    // when the control does NOT implement IDeliveryProviderTypeControl. It exists
    // here only to satisfy the IEmailProviderUserControl contract.
    public void SaveControlValues() { }

    public bool Test() { return true; }

    public bool ValidatePage() { return true; }

    private XMPieWSAPIProxy.EmailProviderParameter MakeParam(string name, string value)
    {
        return new XMPieWSAPIProxy.EmailProviderParameter { m_Name = name, m_Value = value ?? "" };
    }

    private XMPieWSAPIProxy.EmailProviderParameter MakePasswordParam(bool inEncryptRelevantDetails)
    {
        string typed = PasswordTextBox.Text ?? "";
        string value;

        if (typed == scPasswordMask)
        {
            // User did not retype the password - preserve the previously-stored value.
            value = "";
            if (DeliveryProviderParams != null)
            {
                foreach (var p in DeliveryProviderParams)
                    if (p.m_Name == "Password") { value = p.m_Value; break; }
            }
        }
        else
        {
            // Tagging the value asks the framework to encrypt it when writing to DB.
            value = inEncryptRelevantDetails ? GeneralUtils.MarkForEncription(typed) : typed;
        }

        return new XMPieWSAPIProxy.EmailProviderParameter { m_Name = "Password", m_Value = value };
    }
}

Parameter Handling Between Form and Runtime

Parameters flow from the dashboard form to the runtime plugin as follows:

  1. The dashboard form returns EmailProviderParameter[] from SaveControlValues(...). Each entry has m_Name and m_Value properties.

  2. The framework persists each parameter as a separate <EmailProviderParameter> element in the provider's stored XML configuration.

  3. At runtime, the plugin receives a serialized EmailProviderParameters XML string in the inEmailProviderParameters argument. The plugin deserializes this XML to read each setting by name.

Composed Plug-in Implementation

When a uProduce job is run using the custom delivery provider, uProduce calls the:

  1. ComposedInitialize method,

  2. ComposedProcess method for each recipient, and

  3. ComposedFinalize method.

The EmailComposedPluginSample provided in the SDK includes EmailComposedSample.cs which demonstrates how to Implement IEmailComposedProvider for composed mode plugins. The plugin receives pre-composed emails and handles delivery.

Copy 
using EmailProviderExInterface;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Net;
using System.Net.Mail;
using System.Xml.Serialization;

namespace EmailComposedPluginSample
{
    public class EmailComposedSample : IEmailComposedProvider, IEmailTrackingProvider
    {
        // Settings deserialized from inEmailProviderParameters in ComposedInitialize.
        // Each one corresponds to a named EmailProviderParameter saved by the dashboard
        // form (see DashboardConfig/EmailComposedSampleUI.ascx.cs).
        private string Server { get; set; }
        private int Port { get; set; }
        private string Username { get; set; }
        private string Password { get; set; }

        public void ComposedAbort(EmailAbortEnum inReason)
        {
            // TODO: Add cleanup here
        }

        public void ComposedFinalize()
        {
            // TODO: Add finalization code here
        }

        public void ComposedInitialize(string inEmailProviderParameters,
            EmailProviderSendContext inContext,
            EmailComposedParameters inParameters,
            ref AutomaticAdors inoutAutomaticAdors)
        {
            // inEmailProviderParameters is a serialized EmailProviderParameters XML
            // produced by the framework from the dashboard form's saved values.
            // Deserialize it into the local classes declared below and pull each
            // setting by name. Keeping the small data classes inside the sample
            // avoids any build-time dependency beyond XMPEmailProviderInterface.dll.
            EmailProviderParameters parameters;
            XmlSerializer serializer = new XmlSerializer(typeof(EmailProviderParameters));
            using (StringReader reader = new StringReader(inEmailProviderParameters))
                parameters = (EmailProviderParameters)serializer.Deserialize(reader);

            Server = GetParamValue(parameters, "Server");
            int port;
            Port = int.TryParse(GetParamValue(parameters, "Port"), NumberStyles.Integer, CultureInfo.InvariantCulture, out port) ? port : 25;
            Username = GetParamValue(parameters, "Username");
            Password = GetParamValue(parameters, "Password");
        }

        private static string GetParamValue(EmailProviderParameters parameters, string name)
        {
            if (parameters == null || parameters.m_Params == null)
                return "";
            foreach (EmailProviderParameter p in parameters.m_Params)
                if (string.Equals(p.m_Name, name, StringComparison.OrdinalIgnoreCase))
                    return p.m_Value;
            return "";
        }

        public void ComposedProcess(EmailComposedProcessParameters inParameters)
        {
            // Create a message and set up the recipients.
            MailMessage message = new MailMessage(
                            inParameters.Header.From.Address,
                            inParameters.Header.To[0].Address,
                            inParameters.Header.Subject,
                            inParameters.HTMLComposedBody);

            SmtpClient client = new SmtpClient(Server, Port);
            if (!string.IsNullOrEmpty(Username))
                client.Credentials = new NetworkCredential(Username, Password);

            try
            {
                client.Send(message);
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception caught in ComposedProcess: {0}",
                        ex.ToString());
                throw (new EmailProviderFatalErrorException(ex.Message));
            }
        }

        public EmailProviderServices EmailServices { get; set; }

        public bool TrackingInitialize(string inEmailProviderParameters, string inEmailProviderTrackingParameters, EmailProviderTrackingContext inContext)
        {
            // TODO: Add initialization code here
            return true;
        }

        /// 

        /// The TrackingProcess method is called every hour by the XMPEmailProvidersTracker
        /// scheduled task on the uProduce server. If you wish to add tracking events,
        /// use this method to query your custom email delivery service to get the events
        /// and pass them to the uProduce tracking database.
        /// 

        /// 
        /// Boolean true/false for success/failure
        public bool TrackingProcess(JobTrackingParameters inJobTrackingParameters)
        {
            foreach (var eventData in QueryYourCustomEmailDeliveryServiceToGetTheEvents(inJobTrackingParameters))
            {
                if (eventData["Type"].ToString() == "opened")
                {
                    EmailServices.EmailTrackingServices.AddEmailOpenedTrackingEvent(
                            inJobTrackingParameters.CampaignID,
                            inJobTrackingParameters.JobID,
                            null,
                            eventData["Email"].ToString(),
                            Convert.ToDateTime(eventData["DateTime"]));
                    continue;
                }

                if (eventData["Type"].ToString() == "failed")
                {
                    EmailServices.EmailTrackingServices.AddEmailFailedTrackingEvent(
                            inJobTrackingParameters.CampaignID,
                            inJobTrackingParameters.JobID,
                            null,
                            eventData["Email"].ToString(),
                            eventData["Details"].ToString(),
                            null,
                            Convert.ToDateTime(eventData["DateTime"]));
                    continue;
                }

                if (eventData["Type"].ToString() == "unsubscribed")
                {
                    EmailServices.EmailTrackingServices.AddEmailUnsubscibedTrackingEvent(
                            inJobTrackingParameters.CampaignID,
                            inJobTrackingParameters.JobID,
                            null,
                            eventData["Email"].ToString(),
                            eventData["Details"].ToString(),
                            null,
                            Convert.ToDateTime(eventData["DateTime"]));
                    continue;
                }

                if (eventData["Type"].ToString() == "clicked")
                {
                    EmailServices.EmailTrackingServices.AddLinkClickedTrackingEvent(
                            inJobTrackingParameters.CampaignID,
                            inJobTrackingParameters.JobID,
                            null,
                            eventData["Email"].ToString(),
                            eventData["Details"].ToString(),
                            Convert.ToDateTime(eventData["DateTime"]));
                    continue;
                }
            }

            return true;
        }

        public bool TrackingFinalize()
        {
            // TODO: Add finalization code here
            return true;
        }

        public void TrackingAbort(EmailAbortEnum inReason)
        {
            // TODO: Add cleanup here
        }

        /// 

        /// Just used for the example of simulating getting events from external system.
        /// In reality the events need to be fetched for specific job\campaign.
        /// Also only events that where not handled before, so no duplicates.
        /// 

        /// The job tracking information to get the events for
        /// An example list of events
        private List> QueryYourCustomEmailDeliveryServiceToGetTheEvents(JobTrackingParameters inJobTrackingParameters)
        {
            return new List> {
                new Dictionary()
                {
                    { "Email",  "john.miller@gmail.com" },
                    { "Type", "opened" },
                    { "DateTime", DateTime.UtcNow },
                    { "Details", null }
                },
                new Dictionary()
                {
                    { "Email",  "john.miller@gmail.com" },
                    { "Type", "unsubscribed" },
                    { "DateTime", DateTime.UtcNow },
                    { "Details", null }
                },
                new Dictionary()
                {
                    { "Email",  "jane.doe@gmail.com" },
                    { "Type", "failed" },
                    { "DateTime", DateTime.UtcNow },
                    { "Details", "Hard Bounce" }
                }
            };
        }
    }

    // Local data classes matching the XML the runtime sends in inEmailProviderParameters.
    // The framework persists each saved setting as one EmailProviderParameter element
    // under a single EmailProviderParameters root. Declaring these locally lets
    // XmlSerializer fill them in without taking a build-time dependency beyond the
    // XMPEmailProviderInterface.dll already referenced by this project.
    [XmlRoot("EmailProviderParameters")]
    public class EmailProviderParameters
    {
        public EmailProviderParameter[] m_Params;
    }

    public class EmailProviderParameter
    {
        public string m_Name;
        public string m_Value;
    }
}

Note: The EmailProviderParameters, EmailProviderParameter, and GetParamValue helper are declared inline within the plugin. Keeping the deserialization local means the plugin only needs to reference XMPEmailProviderInterface.dll — no additional XMPie DLL is required.

Template User Control Implementation

User Control Implementation

The user control provides the configuration interface displayed in the uProduce Dashboard when administrators set up your delivery provider: (Settings > Delivery Providers > New) and (Settings > Delivery Providers > Edit).

The EmailTemplatePluginSample provided in the SDK includes a folder named DashboardConfig that includes the sample User Control EmailTemplateSampleUI.ascx.

User Control (.ascx)

The .ascx file defines the form layout. The sample demonstrates the display of text input field and label Output Folder in a table layout that matches other dashboard delivery provider forms. The email template and data files will be save to this location:

Copy 
<%@ Control Language="C#" AutoEventWireup="true" 
    CodeBehind="EmailTemplateSampleUI.ascx.cs" 
    Inherits="EmailSampleUI.EmailTemplateSampleUI" %>
<%-- Sample dashboard form for a template (export) custom email delivery provider.
     Demonstrates the modern IDeliveryProviderTypeControl pattern. --%>
<table border="0" cellspacing="4" cellpadding="0" width="100%" style="padding-left: 10px">
    <tr>
        <td style="width: 160px;">
            <asp:Label runat="server" CssClass="form-prompt" Text="Output Folder:"></asp:Label>
        </td>
        <td>
            <asp:TextBox ID="OutputFolderTextBox" runat="server" CssClass="formtext" Width="500px"></asp:TextBox>
        </td>
    </tr>
</table>

IDeliveryProviderTypeControl Implementation

The code-behind EmailTemplateSampleUI.ascx.cs implements XMPieDashboard.IDeliveryProviderTypeControl, which extends the base IEmailProviderUserControl interface.

Note: IEmailProviderUserControl is the base interface and is still valid. However, plugins should implement the extended IDeliveryProviderTypeControl interface for full functionality including password encryption support.

Key aspects of the implementation:

  • The control implements XMPieDashboard.IDeliveryProviderTypeControl

  • DeliveryProviderParams is a typed array of EmailProviderParameter — one entry per setting (Server, Port, Username, Password)

  • PopulateControlValues() loads stored parameters by name via a switch on m_Name

  • SaveControlValues(bool inEncryptRelevantDetails) builds the parameter array. When inEncryptRelevantDetails is true, sensitive fields are wrapped with GeneralUtils.MarkForEncription so the framework persists them encrypted

  • Passwords are never echoed back; the form shows a mask and preserves the stored value if the user does not retype

Copy 
using System;
using System.Collections.Generic;
using System.Web.UI;
using EmailProviderExInterface;
using XMPieDashboard;

public partial class EmailTemplateSampleUI : System.Web.UI.UserControl, IDeliveryProviderTypeControl
{
    public string DeliveryProviderID
    {
        get { return (string)ViewState["DeliveryProviderID"]; }
        set { ViewState["DeliveryProviderID"] = value; }
    }

    public string Name
    {
        get { return (string)ViewState["Name"]; }
        set { ViewState["Name"] = value; }
    }

    public int TypeID
    {
        get { return (int)ViewState["TypeID"]; }
        set { ViewState["TypeID"] = value; }
    }

    public bool SupportTest
    {
        get { return ViewState["SupportTest"] != null && (bool)ViewState["SupportTest"]; }
        set { ViewState["SupportTest"] = value; }
    }

    public XMPieWSAPIProxy.EmailProviderParameter[] DeliveryProviderParams
    {
        get { return (XMPieWSAPIProxy.EmailProviderParameter[])ViewState["DeliveryProviderParams"]; }
        set { ViewState["DeliveryProviderParams"] = value; }
    }

    // Legacy interface property - retained because IDeliveryProviderTypeControl
    // extends IEmailProviderUserControl. Not used by the modern path.
    public string DeliveryProviderParameters { get; set; }

    public string InitControls() { return null; }

    public void PopulateControlValues()
    {
        if (DeliveryProviderID == "-1" || string.IsNullOrEmpty(DeliveryProviderID))
        {
            SupportTest = true;
            return;
        }

        DeliveryProvider deliveryProvider = DeliveryProvider.Get(DeliveryProviderID);
        Name = deliveryProvider.Name;
        DeliveryProviderParams = DeliveryProvider.GetDeliveryProviderParameters(DeliveryProviderID);

        foreach (var p in DeliveryProviderParams)
        {
            if (p.m_Name == "OutputFolder")
                OutputFolderTextBox.Text = p.m_Value;
        }

        SupportTest = true;
    }

    // Modern save: build a structured EmailProviderParameter[] with one entry per
    // setting. The framework persists each as a separate 
    // element in the stored XML.
    public void SaveControlValues(bool inEncryptRelevantDetails)
    {
        DeliveryProviderParams = new[]
        {
            new XMPieWSAPIProxy.EmailProviderParameter
            {
                m_Name = "OutputFolder",
                m_Value = OutputFolderTextBox.Text ?? "",
            },
        };
    }

    // Legacy interface method - the framework's edit page only calls this overload
    // when the control does NOT implement IDeliveryProviderTypeControl. It exists
    // here only to satisfy the IEmailProviderUserControl contract.
    public void SaveControlValues() { }

    public bool Test() { return true; }

    public bool ValidatePage() { return true; }
}

Parameter Handling Between Form and Runtime

Parameters flow from the dashboard form to the runtime plugin as follows:

  1. The dashboard form returns EmailProviderParameter[] from SaveControlValues(...). Each entry has m_Name and m_Value properties.

  2. The framework persists each parameter as a separate <EmailProviderParameter> element in the provider's stored XML configuration.

  3. At runtime, the plugin receives a serialized EmailProviderParameters XML string in the inEmailProviderParameters argument. The plugin deserializes this XML to read each setting by name.

Template Plug-in Implementation

When a uProduce job is run using the custom delivery provider, uProduce calls the:

  1. TemplateInitialize method,

  2. TemplateProcess method for each recipient, and then

  3. TemplateFinalize method.

The EmailTemplatePluginSample provided in the SDK includes EmailTemplateSample.cs which demonstrates how to Implement IEmailTemplateProvider for template mode plugins.

In the sample, we create an email template file and a CSV file containing the recipient information. For each call of the TemplateProcess method, we save each recipient record to the CSV file.

In a real implementation, you might prefer to store in memory a number of recipient records and save them to a CSV file as a batch. Then, in the TemplateFinalize you can use the template and the CSV file to send the actual emails.

Implement IEmailTemplateProvider for template mode plugins. The plugin receives a template and recipient data, then composes and delivers emails.

Copy 
using EmailProviderExInterface;
using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using System.Text.RegularExpressions;
using System.Xml.Serialization;

namespace EmailTemplatePluginSample
{
    public class EmailTemplateSample : IEmailTemplateProvider, IEmailTrackingProvider
    {
        private const string CSVFileName = @"EmailList.csv";
        private const string TemplateFileName = @"HTMLTemplate.txt";

        private EmailHeader Header { get; set; }
        private string RootOutputPath { get; set; }

        private string outputPath;
        private string csvOutputFile;

        public void TemplateAbort(EmailAbortEnum inReason)
        {
            // TODO: Add cleanup here
        }

        public void TemplateInitialize(string inEmailProviderParameters,
                EmailProviderSendContext inContext,
                EmailTemplateParameters inParameters,
                AutomaticAdors inAutomaticAdors)
        {
            // inEmailProviderParameters is a serialized EmailProviderParameters XML
            // produced by the framework from the dashboard form's saved values.
            // Deserialize it into the local classes declared below and pull each
            // setting by name. Keeping the small data classes inside the sample
            // avoids any build-time dependency beyond XMPEmailProviderInterface.dll.
            EmailProviderParameters parameters;
            XmlSerializer serializer = new XmlSerializer(typeof(EmailProviderParameters));
            using (StringReader reader = new StringReader(inEmailProviderParameters))
                parameters = (EmailProviderParameters)serializer.Deserialize(reader);

            RootOutputPath = GetParamValue(parameters, "OutputFolder");

            outputPath = Path.Combine(RootOutputPath,
                    inContext.JobID.ToString());
            if (Directory.Exists(outputPath))
                Directory.Delete(outputPath, true);

            Directory.CreateDirectory(outputPath);

            File.WriteAllText(Path.Combine(outputPath, TemplateFileName),
                inParameters.HTMLTemplateBody);

            Header = inParameters.Header;
            csvOutputFile = Path.Combine(outputPath, CSVFileName);
        }

        public void TemplateProcess(EmailTemplateProcessParameters inParameters)
        {
            try
            {
                StringBuilder row = new StringBuilder();
                if (!File.Exists(csvOutputFile))
                {
                    // write the title row
                    row.Append("To");
                    foreach (string key in inParameters.DynamicObjects.Keys)
                    {
                        row.Append(",");
                        row.Append(key);
                    }
                    row.Append("\n");
                    File.WriteAllText(csvOutputFile, row.ToString());
                }
                row.Clear();

                string toAddress = ComposeString(Header.To[0].Address, inParameters.DynamicObjects);
                row.Append(toAddress);
                foreach (string val in inParameters.DynamicObjects.Values)
                {
                    row.Append(",");
                    row.Append(val);
                }
                row.Append("\n");

                File.AppendAllText(csvOutputFile, row.ToString());
            }
            catch (Exception ex)
            {
                Console.WriteLine("Exception caught in TemplateProcess: {0}", ex.ToString());
                throw (new EmailProviderFatalErrorException(ex.Message));
            }
        }

        public void TemplateFinalize()
        {
            // TODO: Add finalization code here
        }

        private string ComposeString(string unComposedString, Dictionary dynamicObjects)
        {
            string regXMPieAdorAll = AutomaticAdors.XMPIE_DYNAMIC_START_TAG + @"\s*(.*?)\s*" + AutomaticAdors.XMPIE_DYNAMIC_END_TAG;

            MatchCollection mc = Regex.Matches(unComposedString, regXMPieAdorAll);
            string composedStr = unComposedString;
            foreach (Match m in mc)
            {
                composedStr = unComposedString.Replace(m.Groups[0].Value,
                    dynamicObjects[m.Groups[1].Value]);
            }

            return composedStr;
        }

        public EmailProviderServices EmailServices { get; set; }

        public bool TrackingInitialize(string inEmailProviderParameters, string inEmailProviderTrackingParameters, EmailProviderTrackingContext inContext)
        {
            // TODO: Add initialization code here
            return true;
        }

        /// 

        /// The TrackingProcess method is called every hour by the XMPEmailProvidersTracker
        /// scheduled task on the uProduce server. If you wish to add tracking events,
        /// use this method to query your custom email delivery service to get the events
        /// and pass them to the uProduce tracking database.
        /// 

        /// 
        /// Boolean true/false for success/failure
        public bool TrackingProcess(JobTrackingParameters inJobTrackingParameters)
        {
            foreach (var eventData in QueryYourCustomEmailDeliveryServiceToGetTheEvents(inJobTrackingParameters))
            {
                if (eventData["Type"].ToString() == "opened")
                {
                    EmailServices.EmailTrackingServices.AddEmailOpenedTrackingEvent(
                            inJobTrackingParameters.CampaignID,
                            inJobTrackingParameters.JobID,
                            null,
                            eventData["Email"].ToString(),
                            Convert.ToDateTime(eventData["DateTime"]));
                    continue;
                }

                if (eventData["Type"].ToString() == "failed")
                {
                    EmailServices.EmailTrackingServices.AddEmailFailedTrackingEvent(
                            inJobTrackingParameters.CampaignID,
                            inJobTrackingParameters.JobID,
                            null,
                            eventData["Email"].ToString(),
                            eventData["Details"].ToString(),
                            null,
                            Convert.ToDateTime(eventData["DateTime"]));
                    continue;
                }

                if (eventData["Type"].ToString() == "unsubscribed")
                {
                    EmailServices.EmailTrackingServices.AddEmailUnsubscibedTrackingEvent(
                            inJobTrackingParameters.CampaignID,
                            inJobTrackingParameters.JobID,
                            null,
                            eventData["Email"].ToString(),
                            eventData["Details"].ToString(),
                            null,
                            Convert.ToDateTime(eventData["DateTime"]));
                    continue;
                }

                if (eventData["Type"].ToString() == "clicked")
                {
                    EmailServices.EmailTrackingServices.AddLinkClickedTrackingEvent(
                            inJobTrackingParameters.CampaignID,
                            inJobTrackingParameters.JobID,
                            null,
                            eventData["Email"].ToString(),
                            eventData["Details"].ToString(),
                            Convert.ToDateTime(eventData["DateTime"]));
                    continue;
                }
            }

            return true;
        }

        public bool TrackingFinalize()
        {
            // TODO: Add finalization code here
            return true;
        }

        public void TrackingAbort(EmailAbortEnum inReason)
        {
            // TODO: Add cleanup here
        }

        /// 

        /// Just used for the example of simulating getting events from external system.
        /// In reality the events need to be fetched for specific job\campaign.
        /// Also only events that where not handled before, so no duplicates.
        /// 

        /// The job tracking information to get the events for
        /// An example list of events
        private List> QueryYourCustomEmailDeliveryServiceToGetTheEvents(JobTrackingParameters inJobTrackingParameters)
        {
            return new List> {
                new Dictionary()
                {
                    { "Email",  "john.miller@gmail.com" },
                    { "Type", "opened" },
                    { "DateTime", DateTime.UtcNow },
                    { "Details", null }
                },
                new Dictionary()
                {
                    { "Email",  "john.miller@gmail.com" },
                    { "Type", "unsubscribed" },
                    { "DateTime", DateTime.UtcNow },
                    { "Details", null }
                },
                new Dictionary()
                {
                    { "Email",  "jane.doe@gmail.com" },
                    { "Type", "failed" },
                    { "DateTime", DateTime.UtcNow },
                    { "Details", "Hard Bounce" }
                }
            };
        }

        private static string GetParamValue(EmailProviderParameters parameters, string name)
        {
            if (parameters == null || parameters.m_Params == null)
                return "";
            foreach (EmailProviderParameter p in parameters.m_Params)
                if (string.Equals(p.m_Name, name, StringComparison.OrdinalIgnoreCase))
                    return p.m_Value;
            return "";
        }
    }

    // Local data classes matching the XML the runtime sends in inEmailProviderParameters.
    // The framework persists each saved setting as one EmailProviderParameter element
    // under a single EmailProviderParameters root. Declaring these locally lets
    // XmlSerializer fill them in without taking a build-time dependency beyond the
    // XMPEmailProviderInterface.dll already referenced by this project.
    [XmlRoot("EmailProviderParameters")]
    public class EmailProviderParameters
    {
        public EmailProviderParameter[] m_Params;
    }

    public class EmailProviderParameter
    {
        public string m_Name;
        public string m_Value;
    }
}

Tracking

Overview

The tracking mechanism in the delivery provider plugin is called every hour by the "XMPEmailProvidersTracker" scheduled task running on the uProduce server. The TrackingProcess method in the plugin allows you to query your custom delivery provider for any tracking events, and to add them to the uProduce Tracking database so that email sends, opens, bounces, and other events are available for tracking together with events from other touchpoints in the cross media campaign.

To add the Tracking capability to your custom email delivery provider plugin, you must implement the tracking interface in addition to the email plug-in (either Template or Composed).

Implement the tracking interface

  1. Set the EmailComposedSample / EmailTemplateSample class to inherit from IEmailTrackingProvider in addition to IEmailComposedProvider / IEmailTemplateProvider.

    Copy 
    public class EmailTemplateSample : IEmailTemplateProvider,
                                       IEmailTrackingProvider

    or

    Copy 
    public class EmailComposedSample : IEmailComposedProvider,
                                       IEmailTrackingProvider

    Below is the sample code for IEmailTrackingProvider interface implementation:

    Copy 
    public bool TrackingInitialize(string inEmailProviderParameters, 
            string inEmailProviderTrackingParameters, 
            EmailProviderTrackingContext inContext)
    {
        // TODO: Add initialization code here
        return true;
    }

    /// <summary>
    /// The TrackingProcess method is called every hour by the XMPEmailProvidersTracker
    /// scheduled task on the uProduce server. If you wish to add tracking events,
    /// use this method to query your custom email delivery service to get the events
    /// and pass them to the uProduce tracking database.
    /// </summary>
    /// <param name="inJobTrackingParameters"></param>
    /// <returns>Boolean true/false for success/failure</returns>
    public bool TrackingProcess(JobTrackingParameters 
            inJobTrackingParameters)
    {
        foreach (var eventData in QueryYourCustomEmailDeliveryServiceToGetTheEvents(
                inJobTrackingParameters))
        {
            if (eventData["Type"].ToString() == "opened")
            {
                EmailServices.EmailTrackingServices.AddEmailOpenedTrackingEvent(
                        inJobTrackingParameters.CampaignID,
                        inJobTrackingParameters.JobID,
                        null,
                        eventData["Email"].ToString(),
                        Convert.ToDateTime(eventData["DateTime"]));
                continue;
            }

            if (eventData["Type"].ToString() == "failed")
            {
                EmailServices.EmailTrackingServices.AddEmailFailedTrackingEvent(
                        inJobTrackingParameters.CampaignID,
                        inJobTrackingParameters.JobID,
                        null,
                        eventData["Email"].ToString(),
                        eventData["Details"].ToString(),
                        null,
                        Convert.ToDateTime(eventData["DateTime"]));
                continue;
            }

            if (eventData["Type"].ToString() == "unsubscribed")
            {
                EmailServices.EmailTrackingServices.AddEmailUnsubscibedTrackingEvent(
                        inJobTrackingParameters.CampaignID,
                        inJobTrackingParameters.JobID,
                        null,
                        eventData["Email"].ToString(),
                        eventData["Details"].ToString(),
                        null,
                        Convert.ToDateTime(eventData["DateTime"]));
                continue;
            }

            if (eventData["Type"].ToString() == "clicked")
            {
                EmailServices.EmailTrackingServices.AddLinkClickedTrackingEvent(
                        inJobTrackingParameters.CampaignID,
                        inJobTrackingParameters.JobID,
                        null,
                        eventData["Email"].ToString(),
                        eventData["Details"].ToString(),
                        Convert.ToDateTime(eventData["DateTime"]));
                continue;
            }
        }

        return true;
    }

    public bool TrackingFinalize()
    {
        // TODO: Add finalization code here
        return true;
    }

    public void TrackingAbort(EmailAbortEnum inReason)
    {
        // TODO: Add cleanup here
    }

    /// <summary>
    /// Just used for the example of simulating getting events from external system.
    /// In reality the events need to be fetched for specific job\campaign.
    /// Also only events that where not handled before, so no duplicates.
    /// </summary>
    /// <param name="inJobTrackingParameters">The job tracking information to get the events for</param>
    /// <returns>An example list of events</returns>
    private List<Dictionary<string, object>> QueryYourCustomEmailDeliveryServiceToGetTheEvents(
            JobTrackingParameters inJobTrackingParameters)
    {
        return new List<Dictionary<string, object>> {
            new Dictionary<string, object>()
            {
                { "Email",  "john.miller@gmail.com" },
                { "Type", "opened" },
                { "DateTime", DateTime.UtcNow },
                { "Details", null }
            },
            new Dictionary<string, object>()
            {
                { "Email",  "john.miller@gmail.com" },
                { "Type", "unsubscribed" },
                { "DateTime", DateTime.UtcNow },
                { "Details", null }
            },
            new Dictionary<string, object>()
            {
                { "Email",  "jane.doe@gmail.com" },
                { "Type", "failed" },
                { "DateTime", DateTime.UtcNow },
                { "Details", "Hard Bounce" }
            }
        };
    }

  2. Copy the EmailTemplatePluginSample.dll / EmailComposedPluginSample.dll with the tracking implementation to \XMPie\XMPieExec

Note: In configurations with multiple extension servers, the binary files should be copied to all extensions running email production.

Verification

The tracking mechanism is called every hour, so you should see the events in the tracking database after the task scheduler task execution.

On-Demand Interfaces

For real-time email delivery in Circle scenarios, implement the on-demand interfaces:

  • IEmailComposedOnDemandProvider

  • IEmailTemplateOnDemandProvider

User Control Deployment

  1. Create your user control form or edit one of the samples provided in the SDK.

  2. Copy your .ascx form and its .ascx.cs code-behind file to the uProduce servers X:\XMPie\XMPieDashboard\Settings\DeliveryProviders folder. Note: these files are not built standalone — they are deployment artifacts.

  3. Edit the X:\XMPie\XMPieDashboard\PrecompiledApp.config file and ensure that updatable is set to true. Note: if you need to change the value to true, for the change to take effect you will need to restart IIS by running iisreset in a command window.

Multi-server configurations: The above steps should be completed on all director servers that run the dashboard application.

Plugin DLL Deployment

  1. Create a Visual C# Class Library project or edit one of the samples provided in the SDK.

  2. Add a reference to XMPEmailProviderInterface.dll (This dll is located on your uProduce server at X:\XMPie\XMPieExec.

  3. Implement IEmailComposedProvider or IEmailTemplateProvider as described above.

  4. Build your project.

  5. Copy the compiled DLL to \XMPie\XMPieExec on the uProduce server

Multi-server configurations: Custom assemblies must be deployed to \XMPie\XMPieExec on all extension servers. User controls must be replicated to the Dashboard directories on all web servers.

Database Registration

Register your delivery provider in the TBL_DELIVERY_PROVIDER_TYPES table. The following SQL provides an example for adding the Sample Composed plug-in that is provided in the SDK:

Copy 
INSERT INTO TBL_DELIVERY_PROVIDER_TYPES (
    DeliveryProviderTypeName,
    DeliveryProviderTypeClassName,
    DeliveryProviderTypeAssembly,
    DeliveryProviderTypeControlName,
    DeliveryProviderTypeMode
) VALUES (
    'My Custom Provider',
    'MyNamespace.EmailComposedSample',
    'MyEmailProvider.dll',
    'DeliveryProviders/EmailComposedSampleUI',
    1  -- 1 = Composed, 0 = Template
);

Note: DeliveryProviderTypeControlName is the dashboard-relative path to the .ascx file, not the on-disk path in your plugin project.

Circle synchronization

After adding the new email provider to uProduce, it is immediately available in the uProduce dashboard as you can see in the previous Verification step.

If you are sending emails via Circle, there is a scheduled task that runs at midnight to synchronize the delivery providers listed in Circle. You can either wait overnight for the automated synchronization process to run, or on the uProduce server, open the Windows Task Scheduler and run the XMPEmailProvidersSubscriberListSyncher Task that appears in th Task Scheduler Library.

Verify the new delivery provider installation

  1. In uProduce dashboard, go to the Settings > Delivery Providers tab.

  2. Click New to set up a new delivery provider.

  3. In the Type dropdown list, select your newly added delivery provider.

  4. In the Name field, enter a name of a Delivery Provider, and enter the details required for your user control.

  5. Create an Email Activity and select the new Delivery Provider in the Email Provider dropdown list.

  6. You can now test your new Delivery Provider by sending emails.

EmailProviderExInterface namespace reference

Classes

AutomaticAdors

Special ADOR Objects that can be overridden with Delivery Provider implementation, for example View in browser etc.

Constructors

AutomaticAdors() – Creates a new instance of the AutomaticAdors class.

Fields

Name

CANSPAM_COMPANY_ADDRESS_ADOR

Description

Senders address

Syntax

public const string CANSPAM_COMPANY_ADDRESS_ADOR

 

Name

CANSPAM_COMPANY_CITY_ADOR

Description

Sender's city name

Syntax

public const string CANSPAM_COMPANY_CITY_ADOR

 

Name

CANSPAM_COMPANY_COUNTRY_ADOR

Description

Sender's country

Syntax

public const string CANSPAM_COMPANY_COUNTRY_ADOR

 

Name

CANSPAM_COMPANY_NAME_ADOR

Description

Business name

Syntax

public const string CANSPAM_COMPANY_NAME_ADOR

 

Name

CANSPAM_COMPANY_STATE_ADOR

Description

Sender's state

Syntax

public const string CANSPAM_COMPANY_STATE_ADOR

 

Name

CANSPAM_COMPANY_ZIPCODE_ADOR

Description

Sender's ZIP code

Syntax

public const string CANSPAM_COMPANY_ZIPCODE_ADOR

 

Name

CANSPAM_UNSUBSCRIBE_URL_ADOR

Description

Unsubscribe URL for commercial emails

Syntax

public const string CANSPAM_UNSUBSCRIBE_URL_ADOR

 

Name

VIEW_IN_BROWSER

Description

View in browser link

Syntax

public const string VIEW_IN_BROWSER

 

Name

XMPIE_DYNAMIC_END_TAG

Description

ADOR Object 'End' tag

Syntax

public const string XMPIE_DYNAMIC_END_TAG

 

Name

XMPIE_DYNAMIC_START_TAG

Description

ADOR Object 'Start' tag

Syntax

public const string XMPIE_DYNAMIC_START_TAG

 

Name

XMPIE_RECIPIENT_KEY_ADOR

Description

Recipient Key

Syntax

public const string XMPIE_RECIPIENT_KEY_ADOR

 

Name

XMPIE_RI_PRIMARY_FIELD_ADOR_MAX_LENGTH

Description

Maximum length of the Recipient Key ADOR

Syntax

public const int XMPIE_RI_PRIMARY_FIELD_ADOR_MAX_LENGTH

Properties

Name

AutomaticAdorsDict

Description

The dictionary containing ADOR Objects

Syntax

public Dictionary<string, string> AutomaticAdorsDict { get; }

EmailAddress

Constructors

EmailAddress() – Initializes a new instance of the EmailAddress class.

EmailAddress(EmailAddress) - Initializes a new instance of the EmailAddress class using the specified address.

Properties

Name

Address

Description

Email address

Syntax

public string Address { get; set; }

 

Name

Display

Description

Email address display name

Syntax

public string Display { get; set; }

EmailComposedParameters

Composed parameters - for future use.

EmailComposedProcessParameters

Composed process parameters. This class contains email message data, such as recipient ID, header, message body, etc.

Constructors

EmailComposedParameters() – Initializes a new instance of the EmailComposedParameters class

Properties

Name

Header

Description

Email header

Syntax

public EmailHeader Header { get; set; }

 

Name

HTMLComposedBody

Description

Composed HTML message body

Syntax

public string HTMLComposedBody { get; set; }

 

Name

RecipientID

Description

Recipient ID

Syntax

public string RecipientID { get; set; }

 

Name

TEXTComposedBody

Description

Composed Text message body

Syntax

public string TEXTComposedBody { get; set; }

EmailDynamicObjectInformation

Dynamic object type and information

Constructors

EmailDynamicObjectInformation() – Initializes a new instance of the EmailDynamicObjectInformation class

Properties

Name

DynamicObjectType

Description

Dynamic object type

Syntax

public EmailDynamicObjectTypeEnum DynamicObjectType { get; set; }

EmailDynamicObjectInformation_Tabular

Dynamic object type and information – tabular

Constructors

EmailDynamicObjectInformation_Tabular() - Initializes a new instance of the EmailDynamicObjectInformation_Tabular class

Fields

Name

TABULAR_COL_DELIMITER

Description

delimiter for tabular column

Syntax

public const string TABULAR_COL_DELIMITER

 

Name

TABULAR_ROW_DELIMITER

Description

delimiter for tabular row

Syntax

public const string TABULAR_ROW_DELIMITER

Properties

Name

ColumnNameList

Description

Tabular column names

Syntax

 
public List<string> ColumnNameList 
{ get; set; }

 

Name

DynamicObjectType

Description

Dynamic object type (Inherited from EmailDynamicObjectInformation)

Syntax

public EmailDynamicObjectTypeEnum DynamicObjectType { get; set; }

EmailGeneralParameters

General email parameters

Constructors

EmailGeneralParameters() - Initializes a new instance of the EmailGeneralParameters class

Properties

Name

Header

Description

Email header

Syntax

public EmailHeader Header { get; set; }

EmailHeader

Email header

Constructors

EmailHeader() - Initializes an empty instance of the EmailHeader class.

EmailHeader(EmailHeader) - Initializes an empty instance of the EmailHeader class by using the specified EmailHeader class objects.

Properties

Name

BCC

Description

The list of email addresses of all the blind carbon copy (BCC) recipients.

Syntax

public EmailAddress[] BCC { get; set; }

 

Name

CC

Description

The list of email addresses of all the carbon copy (CC) recipients.

Syntax

public EmailAddress[] CC { get; set; }

 

Name

CharacterSet

Description

The email message body encoding.

Syntax

public string CharacterSet { get; set; }

 

 

Name

From

Description

The 'From' address of the email message.

Syntax

public EmailAddress From { get; set; }

 

Name

ReplyTo

Description

The 'ReplyTo' address of the email message.

Syntax

public EmailAddress[] ReplyTo { get; set; }

 

 

Name

Subject

Description

The email message subject line.

Syntax

public string Subject { get; set; }

 

Name

To

Description

The list of email addresses of all email recipients.

Syntax

public EmailAddress[] To { get; set; }

EmailProviderBaseException

Email Delivery Provider exception. If the Delivery Provider encounters an error, it can return an exception to stop the email process.

Constructors

EmailProviderBaseException() - Email Provider Base Exception

EmailProviderBaseException(String) - Email Provider Base Exception with string message.

Syntax

public EmailProviderBaseException()
public EmailProviderBaseException(
  string message
)

EmailProviderContext

uProduce data that can be used by the Delivery provider to perform various operations

Constructors

EmailProviderContext() - Initializes a new instance of the EmailProviderContext class

Fields

Name

EmailContextProperty_EstimatedRecordCount

Description

Estimated record count

Syntax

public const string EmailContextProperty_EstimatedRecordCount

 

Name

EmailContextProperty_IsComposedBody

Description

'True' if the email message body is created using the URL mechanism or a template.

Syntax

public const string EmailContextProperty_IsComposedBody

 

Name

EmailContextProperty_IsLinksClicksTracked

Description

'True' if the links clicks in the email body are tracked.

Syntax

public const string EmailContextProperty_IsLinksClicksTracked

 

 

Name

EmailContextProperty_IsTrackedJob

Description

'True' if the job is tracked.

Syntax

public const string EmailContextProperty_IsTrackedJob

 

Name

EmailContextProperty_JobOutputFolder

Description

Job output folder.

Syntax

public const string EmailContextProperty_JobOutputFolder

 

 

Name

EmailContextProperty_MachineID

Description

Machine ID - unique ID of the current uProduce server

Syntax

public const string EmailContextProperty_MachineID

 

Name

EmailContextProperty_OldMachineID

Description

Obsolete - old Machine ID

Syntax

public const string EmailContextProperty_OldMachineID

 

Name

EmailContextProperty_TouchPointGUID

Description

TouchPoint Guid - unique GUID of the touch point

Syntax

public const string EmailContextProperty_TouchPointGUID

 

Name

EmailContextProperty_uProduceSystemID

Description

System ID - unique ID of the current uProduce server

Syntax

public const string EmailContextProperty_uProduceSystemID

Properties

Name

CustomerID

Description

Customer ID

Syntax

public int CustomerID { get; set; }

 

Name

CustomerName

Description

Customer name

Syntax

public string CustomerName { get; set; }

 

Name

EmailContextProperties

Description

A dictionary of additional email contexts, for example, email type (commercial or transactional)

Syntax

public Dictionary<string, string> EmailContextProperties { get; set; }

 

Name

EmailProviderID

Description

Delivery provider ID

Syntax

public int EmailProviderID { get; set; }

 

Name

EmailProviderName

Description

Delivery provider name

Syntax

public string EmailProviderName { get; set; }

 

Name

Proxy

Description

Proxy information

Syntax

public ProxyInfo Proxy { get; set; }

EmailProviderFatalErrorException

Email Delivery Provider fatal error exception. This exception stops the email send process.

Constructors

EmailProviderFatalErrorException() - Email Provider Fatal Error Exception

EmailProviderFatalErrorException(string) - Email Provider Fatal Error Exception with string message

EmailProviderProcessException

Email Provider Process Exception. This exception stops the email send process for the current recipient. The sending operation will continue for all the other recipients.

Constructors

EmailProviderProcessException() - Email Provider Process Exception

EmailProviderProcessException(String) - Email Provider Process Exception with string message

EmailProviderSendContext

uProduce send data that can be used by the Delivery Provider to perform various tracking operations

Constructors

EmailProviderSendContext() - Initializes a new instance of the EmailProviderSendContext class

Properties

Name

AccountID

Description

Account ID

Syntax

public int AccountID { get; set; }

 

Name

AccountName

Description

Account name

Syntax

public string AccountName { get; set; }

 

Name

CampaignID

Description

Campaign ID

Syntax

public int CampaignID { get; set; }

 

 

Name

CampaignName

Description

Campaign name

Syntax

public string CampaignName { get; set; }

 

Name

CustomerID

Description

Customer ID (Inherited from EmailProviderContext.)

Syntax

public int CustomerID { get; set; }

 

Name

CustomerName

Description

Customer name (Inherited from EmailProviderContext.)

Syntax

public string CustomerName { get; set; }

 

Name

EmailContextProperties

Description

A dictionary of additional email contexts, for example, email type (commercial or transactional) (Inherited from EmailProviderContext.)

Syntax

public Dictionary<string, string> EmailContextProperties { get; set; }

 

Name

EmailProviderID

Description

Delivery Provider ID (Inherited from EmailProviderContext.)

Syntax

public int EmailProviderID { get; set; }

 

Name

EmailProviderName

Description

Delivery Provider name (Inherited from EmailProviderContext.)

Syntax

public string EmailProviderName { get; set; }

 

Name

JobID

Description

Job ID

Syntax

public int JobID { get; set; }

 

Name

JobName

Description

Job name

Syntax

public string JobName { get; set; }

 

 

Name

JobType

Description

Job type

Syntax

public JobTypeEnum JobType { get; set; }

 

Name

Proxy

Description

Proxy information (Inherited from EmailProviderContext.)

Syntax

public ProxyInfo Proxy { get; set; }

 

Name

PublicationID

Description

(For future use) The publication list ID. If 0, the Account ID will be used instead.

Syntax

public int PublicationID { get; set; }

EmailProviderServices

A set of utilities that can be used by the Delivery Provider, for example, to attach a message to the uProduce job.

Constructors

EmailProviderServices() - Initializes a new instance of the EmailProviderServices class

Methods

Name

ReportJobMessage

Description

This method allows to report a message and attach it to the uProduce Job. This message can be viewed in the uProduce Dashboard Job Center.

Syntax

 
public bool ReportJobMessage(
	int inJobID,
	EmailProviderServices.JobMessageSeverity inSeverity,
	string inMessage
)

 

Name

ReportJobProgress

Description

This method allows to report progress message and attach it to the uProduce Job. This message can be viewed in the uProduce Dashboard Job Center.

Syntax

 
public bool ReportJobProgress(
	int inJobID,
	string inMessage
)

Properties

Name

EmailSubscriberListServices

Description

A set of email Subscriber List helper utilities that the Delivery Provider can use to display a message or to update tracking parameters.

Syntax

public EmailProviderServices.EmailProviderSubscriberListServices EmailSubscriberListServices { get; }

 

Name

EmailTrackingServices

Description

A set of email helper utilities that the Delivery Provider

can use to display a message or to update tracking parameters.

Syntax

public EmailProviderServices.EmailProviderTrackingServices EmailTrackingServices { get; }

EmailProviderServices.EmailProviderSubscriberListServices

Email Provider Subscriber List Services

Constructor

EmailProviderSubscriberListServices() - Initializes a new instance of the EmailProviderServices.EmailProviderSubscriberListServices class

Methods

Name

GetEmailProviderSubscriberListID

Description

Get Email Provider subscriber list ID

Syntax

 
public string GetEmailProviderSubscriberListID(
	int inEmailProviderID,
	int inAccountID,
	Nullable<int> inPublicationID
)

 

Name

SyncEmailProviderSubscriberStatus

Description

Synchronize Email Provider Subscriber Status

Syntax

 
public bool SyncEmailProviderSubscriberStatus(
	string inEmailAddress,
	int inAccountID,
	bool inIsActive,
	Nullable<DateTime> inUnsubscribedDate,
	string inUnsubscribedReason,
	Nullable<DateTime> inResubscribedDate,
	string inCustomData
)

EmailProviderServices.EmailProviderTrackingServices

Email provider tracking services

Constructor

EmailProviderTrackingServices() - Initializes a new instance of the EmailProviderServices.EmailProviderTrackingServices class

Methods

Name

AddEmailFailedTrackingEvent

Description

Adds the 'Failed' tracking event to the database.

Syntax

 
public bool AddEmailFailedTrackingEvent(
	int inCampaignID,
	int inJobID,
	string inRecipientID,
	string inEmailAddress,
	string inFailureType,
	string inAdditionalInfo,
	Nullable<DateTime> inUtcDate,
	string inEmailProviderEventID,
	bool inIgnoreIfExist
)

 

Name

AddEmailOpenedTrackingEvent

Description

This method adds the 'Opened' tracking event to the database.

Syntax

 
public bool AddEmailOpenedTrackingEvent(
	int inCampaignID,
	int inJobID,
	string inRecipientID,
	string inEmailAddress,
	Nullable<DateTime> inUtcDate,
	string inEmailProviderEventID,
	bool inIgnoreIfExist
)

 

Name

AddEmailTrackingEvent

Description

Adds a custom 'Tracking' event to the database.

Syntax

 
public bool AddEmailTrackingEvent(
	int inCampaignID,
	int inJobID,
	string inEventType,
	string inRecipientID,
	string inEmailAddress,
	Nullable<DateTime> inUtcDate,
	string inEmailProviderEventID,
	bool inIgnoreIfExist,
	EmailProviderServices
		.EmailProviderTrackingServices
		.TrackingEventProperty[] inProperties
)

 

Name

AddEmailUnsubscibedTrackingEvent

Description

Adds the 'Unsubscribed' tracking event to the database.

Syntax

 
public bool AddEmailUnsubscibedTrackingEvent(
	int inCampaignID,
	int inJobID,
	string inRecipientID,
	string inEmailAddress,
	string inUnsubscribeType,
	string inAdditionalInfo,
	Nullable<DateTime> inUtcDate,
	string inEmailProviderEventID,
	bool inIgnoreIfExist
)

 

Name

AddLinkClickedTrackingEvent

Description

This method adds the 'Email Link Clicked' tracking event to the database.

Syntax

 
public bool AddLinkClickedTrackingEvent(
	int inCampaignID,
	int inJobID,
	string inRecipientID,
	string inEmailAddress,
	string inURL,
	Nullable<DateTime> inUtcDate,
	string inEmailProviderEventID,
	bool inIgnoreIfExist
)

 

Name

UpdateEmailProviderTrackingParameters

Description

Updates the Delivery Provider's tracking parameters.

Syntax

 
public bool UpdateEmailProviderTrackingParameters(
	int inEmailProviderID,
	string inParameters
)

 

Name

UpdateJobTrackingParameters

Description

Updates the Job tracking parameters.

Syntax

 
public bool UpdateJobTrackingParameters(
	int inJobID,
	int inEmailProviderID,
	string inParameters
)

EmailProviderServices.EmailProviderTrackingServices.TrackingEventProperty

Tracking event property - used to specify additional information about the Tracking event.

Constructors

TrackingEventProperty() - Initializes a new instance of the EmailProviderServices.EmailProviderTrackingServices.TrackingEventProperty class

Properties

Name

Name

Description

The name of the property

Syntax

public string Name { get; set; }

 

Name

Value

Description

The value of the property

Syntax

public string Value { get; set; }

EmailProviderTrackingContext

Produce tracking data that can be used by the Delivery Provider to perform various tracking operations

Constructors

EmailProviderTrackingContext() - Initializes a new instance of the EmailProviderTrackingContext class

Properties

Name

CustomerID

Description

Customer ID (Inherited from EmailProviderContext.)

Syntax

public int CustomerID { get; set; }

 

Name

CustomerName

Description

Customer name (Inherited from EmailProviderContext.)

Syntax

public string CustomerName { get; set; }

 

Name

EmailContextProperties

Description

A dictionary of additional email contexts, for example, email type (commercial or transactional) (Inherited from EmailProviderContext.)

Syntax

public Dictionary<string, string> EmailContextProperties { get; set; }

 

Name

EmailProviderID

Description

Delivery Provider ID (Inherited from EmailProviderContext.)

Syntax

public int EmailProviderID { get; set; }

 

Name

EmailProviderName

Description

Delivery Provider name (Inherited from EmailProviderContext.)

Syntax

public string EmailProviderName { get; set; }

 

Name

Proxy

Description

Proxy information (Inherited from EmailProviderContext.)

Syntax

public ProxyInfo Proxy { get; set; }

EmailTemplateParameters

Email Template parameters

Constructors

EmailTemplateParameters() - Initializes a new instance of the EmailTemplateParameters class

Properties

Name

DynamicObjectsType

Description

Dynamic Objects Types - the type of each ADOR - can be text, visibility, tabular, style etc.

Syntax

public Dictionary<string, IEmailDynamicObjectInformation> DynamicObjectsType { get; set; }

 

Name

Header

Description

Header

Syntax

public EmailHeader Header { get; set; }

 

Name

HTMLTemplateBody

Description

HTML template body

Syntax

public string HTMLTemplateBody { get; set; }

 

Name

TEXTTemplateBody

Description

Text template body

Syntax

public string TEXTTemplateBody { get; set; }

EmailTemplateProcessParameters

Email Template process parameters

Constructors

EmailTemplateProcessParameters() - Initializes a new instance of the EmailTemplateProcessParameters class

Properties

Name

DynamicObjects

Description

ADOR Objects dictionary

Syntax

public Dictionary<string, string> DynamicObjects { get; set; }

 

Name

RecipientID

Description

Recipient ID

Syntax

public string RecipientID { get; set; }

JobTrackingParameters

Job tracking parameters

Constructors

JobTrackingParameters() - Initializes a new instance of the JobTrackingParameters class

Properties

Name

CampaignID

Description

Campaign ID

Syntax

public int CampaignID { get; set; }

 

Name

EmailProviderParameters

Description

Delivery provider parameters

Syntax

public string EmailProviderParameters { get; set; }

 

Name

JobID

Description

Job ID

Syntax

public int JobID { get; set; }

ProxyInfo

Proxy information

Constructors

ProxyInfo() - Initializes a new instance of the ProxyInfo class

Properties

Name

FtpPort

Description

The FTP port number

Syntax

public int FtpPort { get; set; }

 

Name

FtpServer

Description

The FTP server name

Syntax

public string FtpServer { get; set; }

 

Name

HttpPort

Description

The HTTP port number

Syntax

public int HttpPort { get; set; }

 

Name

HttpServer

Description

The HTTP server name

Syntax

public string HttpServer { get; set; }

 

Name

HttpsPort

Description

The HTTPS port number

Syntax

public int HttpsPort { get; set; }

 

Name

HttpsServer

Description

The HTTPS server name

Syntax

public string HttpsServer { get; set; }

Interfaces

IEmailComposedOnDemandProvider

Composed On-Demand Provider Interface. The Delivery Provider wishing to use different implementations for batch and On-Demand email send can implement the IEmailComposedOnDemandProvider interface in addition to the IEmailComposedProvider interface.

Methods

Name

ComposedAbort

Description

The Abort method is called when an error occurs. This method allows the Delivery Provider implementation to clean up and close resources, if needed.

Syntax

 
void ComposedAbort(
	EmailAbortEnum inReason
)

 

Name

ComposedFinalize

Description

The Finalize method is called only once at the end of the email send process.

Syntax

void ComposedFinalize()

 

Name

ComposedInitialize

Description

The Initialize method is called only once when the plug-in is loaded to allow the Delivery Provider implementation to initialize its resources.

Syntax

 
void ComposedInitialize(
	string inEmailProviderParameters,
	EmailProviderSendContext inContext,
	EmailComposedParameters inParameters,
	ref AutomaticAdors inoutAutomaticAdors
)

 

Name

ComposedOnDemandProcess

Description

The Process method is called for the On Demand recipient. The Delivery Provider implementation should send an email to this recipient.

Syntax

 
void ComposedOnDemandProcess(
	EmailComposedProcessParameters inParameters
)

IEmailComposedProvider interface

Composed Delivery Provider Interface. This interface can be used when working with Delivery Providers that do not support email composition from a template. These Delivery Providers can only send pre-composed email messages.

Methods

Name

ComposedAbort

Description

The Abort method is called when an error occurs during the email send process or when a user decides to abort the process. This method allows the Delivery provider to clean up and close its resources if needed.

Syntax

 
void ComposedAbort(
	EmailAbortEnum inReason
)

 

Name

ComposedFinalize

Description

The Finalize method is called only once at the end of the email send process.

Syntax

void ComposedFinalize()

 

Name

ComposedInitialize

Description

The ComposedInitialize method is called only once when the plug-in is loaded to allow the Delivery Provider implementation to initialize its resources.

Syntax

 
void ComposedInitialize(
	string inEmailProviderParameters,
	EmailProviderSendContext inContext,
	EmailComposedParameters inParameters,
	ref AutomaticAdors inoutAutomaticAdors
)

 

Name

ComposedProcess

Description

The Process method is called for every recipient. The Delivery Provider can send an email for each recipient, or save the recipient data and send email batches instead.

Syntax

 
void ComposedProcess(
	EmailComposedProcessParameters inParameters
)

Properties

Name

EmailServices

Description

Email services - a set of utilities that can be used by the Delivery Provider, for example, to attach a message to the uProduce job. (Inherited from IEmailProvider.)

Syntax

EmailProviderServices EmailServices { get; set; }

IEmailDynamicObjectInformation

Dynamic object type and information

Properties

Name

DynamicObjectType

Description

Dynamic object type

Syntax

EmailDynamicObjectTypeEnum DynamicObjectType { get; set; }

IEmailProvider

Email Provider Interface. This is the base class for the XMPie Email Interfaces.

Properties

Name

EmailServices

Description

Email services - a set of utilities that can be used by the Delivery Provider, for example, to attach a message to the uProduce job.

Syntax

EmailProviderServices EmailServices { get; set; }

IEmailProviderCustomAction

Used to communicate between the GUI - Provider user control and the provider dll. can be used to validate parameters, email verification etc.

Methods

Name

CustomActionInitialize

Description

The Initialize method is called only once when the plug-in is loaded to allow the Delivery Provider implementation to initialize its resources.

Syntax

 
void CustomActionInitialize(
	EmailProviderSendContext context,
	string inEmailProviderParameters
)

 

Name

DoAction

Description

Action to be called from the GUI - (The provider user control)

Syntax

 
string DoAction(
	string action,
	string actionParams
)

IEmailProviderUserControl

Email Provider User Control. This class is used to implement the Delivery Provider Settings user control.

The user control is displayed in uProduce Dashboard (Settings->Delivery Providers) and contains the private parameters of the Delivery Provider (for example, SMTP server name, user name, etc.).

Methods

Name

InitControls

Description

Allows the Delivery Provider implementation to initialize the controls in the user control.

Syntax

string InitControls()

 

Name

PopulateControlValues

Description

Allows the Delivery Provider to populate the control values in the User Control.

Syntax

void PopulateControlValues()

 

Name

SaveControlValues

Description

Allows the Delivery Provider to save the control's values.

Syntax

void SaveControlValues()

 

Name

Test

Description

If the Delivery Provider supports the Email Test option, this function is called when the user clicks the Test button in the New/Edit Delivery Provider window in uProduce Dashboard.

Syntax

bool Test()

 

Name

ValidatePage

Description

Allows the Delivery Provider to validate the Delivery Provider Settings page before saving.

Syntax

bool ValidatePage()

Properties

Name

DeliveryProviderID

Description

Delivery Provider ID

Syntax

string DeliveryProviderID { get; set; }

 

Name

DeliveryProviderParameters

Description

Delivery Provider private parameters

Syntax

string DeliveryProviderParameters { get; set; }

 

Name

Name

Description

Delivery Provider Name

Syntax

string Name { get; set; }

 

Name

SupportTest

Description

This property returns 'True' if the Delivery Provider implements the 'Test' option. The 'Test' option allows to test the email sending for a single email address. In uProduce Dashboard, the Test button is available in the Edit/New Delivery Provider window.

Syntax

bool SupportTest { get; set; }

 

Name

TypeID

Description

Delivery Provider Type ID. In custom implementations the ID values start from 1000.

Syntax

int TypeID { get; set; }

IEmailTemplateOnDemandProvider

Template On Demand Provider Interface. The Delivery Provider wishing to use different implementations for batch and On Demand email send, can implement the IEmailTemplateOnDemandProvider interface in addition to the IEmailTemplateProvider interface.

Methods

Name

TemplateAbort

Description

The Abort method is called when an error occurs. This method allows the Delivery Provider implementation to clean up and close resources, if needed

Syntax

 
void TemplateAbort(
	EmailAbortEnum inReason
)

 

Name

TemplateFinalize

Description

The Finalize method is called only once at the end of the email send process.

Syntax

void TemplateFinalize()

 

Name

TemplateInitialize

Description

The Initialize method is called only once when the plug-in is loaded to allow the Delivery Provider implementation to initialize its resources.

Syntax

 
void TemplateInitialize(
	string inEmailProviderParameters,
	EmailProviderSendContext inContext,
	EmailTemplateParameters inParameters,
	AutomaticAdors inAutomaticAdors
)

 

Name

TemplateOnDemandProcess

Description

The Process method is called for the On Demand recipient. The Delivery Provider implementation should send an email to this recipient.

Syntax

 
void TemplateOnDemandProcess(
	EmailTemplateProcessParameters inParameters
)

Properties

Name

EmailService

Description

Email services - a set of utilities that can be used by the Delivery Provider, for example, to attach a message to the uProduce job. (Inherited from IEmailProvider.)

Syntax

EmailProviderServices EmailServices { get; set; }

IEmailTemplateProvider

Email Template Delivery Provider. The Template plug-in can be used by Delivery Providers that know how to compose the email from a template and a list of recipients with ADOR values.

Methods

Name

TemplateAbort

Description

The Abort method is called when an error occurs. This method allows the Delivery Provider implementation to clean up and close resources, if needed.

Syntax

 
void TemplateAbort(
	EmailAbortEnum inReason
)

 

Name

TemplateFinalize

Description

The Finalize method is called only once at the end of the email send process.

Syntax

void TemplateFinalize()

 

Name

TemplateInitialize

Description

The Initialize method is called only once when the plug-in is loaded to allow the Delivery Provider implementation to initialize its resources.

Syntax

 
void TemplateInitialize(
	string inEmailProviderParameters,
	EmailProviderSendContext inContext,
	EmailTemplateParameters inParameters,
	AutomaticAdors inAutomaticAdors
)

 

Name

TemplateProcess

Description

The Process method is called for the On Demand recipient. The Delivery Provider implementation should send an email to this recipient.

Syntax

 
void TemplateProcess(
	EmailTemplateProcessParameters inParameters
)

Properties

Name

EmailServices

Description

Email services - a set of utilities that can be used by the Delivery Provier, for example, to attach a message to the uProduce job. (Inherited from IEmailProvider.)

Syntax

EmailProviderServices EmailServices { get; set; }

IEmailTrackingProvider

Tracking provider. This interface allows the Delivery Provider to add tracking events to the uProduce database. The Tracking implementation is called every hour in order to update the tracked events using the EmailServices API.

Methods

Name

TrackingAbort

Description

The Abort method is called when an error occurs. This method allows the Delivery Provider to clean up and close resources, if needed.

Syntax

 
void TrackingAbort(
	EmailAbortEnum inReason
)

 

Name

TrackingFinalize

Description

The Finalize method is called only once at the end of the email process.

Syntax

bool TrackingFinalize()

 

Name

TrackingInitialize

Description

The Initialize method is called to initalize Delivery Provider's resources.

Syntax

 
bool TrackingInitialize(
	string inEmailProviderParameters,
	string inEmailProviderTrackingParameters,
	EmailProviderTrackingContext inContext
)

 

Name

TrackingProcess

Description

The Process method is called to allow the Delivery Provider to update the tracking events.

Syntax

 
bool TrackingProcess(
	JobTrackingParameters inJobTrackingParameters
)

Properties

Name

EmailServices

Description

Email services - a set of utilities that can be used by the Delivery Provider, for example, to attach a message to the uProduce job. (Inherited from IEmailProvider.)

Syntax

EmailProviderServices EmailServices { get; set; }

Enumerations

EmailAbortEnum

Abort reason values

Members

FatalError

AbortRequest

EmailDynamicObjectTypeEnum

Dynamic object types

Members

Text

TextFile

Graphic

Link

Visibility

Style

Tabular

EmailMessagesTypeEnum

Report message type values

Members

IllegalAddress

Unknown

EmailProviderServices.JobMessageSeverity

Job message severity values: Error, Warning or Information

Members

Error

Warning

Information

JobTypeEnum

Job type values

Members

Send

Test

Preflight

Port

OnDemand

TestProvider