Creating Emails in Eloqua using the API

Using PHP and the RESTful API to create an email from HTML.

This is a bit of a follow on to Dave’s great post on sending emails via the Eloqua API, this time we thought we’d show you how to create the email in the first place.  This is a really scalable solution and provides many benefits including:

  • Less copy & pasting via the Eloqua interface i.e. the HTML source files and the subject lines
  • Less configuring of email groups, folders, footers, headers etc
  • Less copy & pasting via the Eloqua interface i.e. the HTML source and the subject line
  • Less room for human error
  • Expedited workflows

We host all assets via Amazon AWS for speed of delivery and again improved workflows and updating of content. So lets get going, firstly like always we establish connection to our Eloqua instance, using our normal login credentials.

$site = YOUR COMPANY NAME
$user = USERNAME
$password = PASSWORD
$baseUrl = "https://secure.eloqua.com/API/REST/1.0";
$eloquaRequest = new EloquaRequest($site, $user, $password, $baseUrl);

We need to define some static variables to hold the Email Group ID and Folder ID (the folder in Eloqua the email is going to reside in).  These are integer values that we use another 2 API calls to find these values in Eloqua (you can dig around and inspect the Eloqua interface to discover these values but its clunky to say the least).

We define and initialise two objects to hold our data.

class Email
    {  
            public $name;
            public $id;
            public $subject;
            public $htmlContent;
            public $isTracked;    
            public $emailFooterId;
            public $groupFooterId;
            public $senderEmail;
            public $senderName;
            public $replyToEmail;
            public $replyToName;
            public $bounceBackEmail;
            public $folderId;
    }

class HTMLContent
{
public $type;
public $html;
}

Initialise these objects:

$myHTML = new HTMLContent();
$email = new Email();

So now the email can be assembled in HTML using PHP. We upload a set of HTML files and subject lines text files (UTF-8) which we spin through via a loop in PHP using the file names and file extensions to determine and create the email in Eloqua (Eloqua allows you to create multiple emails with the same name, be warned!). All images would be remotely linked but URL’s can go in normally, eg https://community.oracle.com/community/topliners/ but with the additional querystring ‘?elqTrack=true’ appended to them and they will be tracked using the setting ‘isTracked’ as below. So an url would be like :

http://www.google.co.uk?elqTrack=true

$email_content = 'API Testing Script, with a <a href="http://www.google.co.uk?elqTrack=true">tracked url</a>';

We then put it together in the objects.

$myHTML->type = 'RawHtmlContent';
$myHTML->html = $email_content; (This comes from the content of the .html file)

$email->name = NAME TO SAVE EMAIL AS IN ELOQUA (We use the .HTML file name here)
$email->subject = SUBJECT LINE (We use the .txt file content here with the same name as the .html file).
$email->htmlContent = $myHTML; //our myHTML object with content in it.
$email->encodingId = 3;
$email->emailFooterId = 36; //our blank footer with tracking, this could be whatever you choose.
$email->emailHeaderId = 17; //our blank header, our email content contains everything we need.
$email->isTracked = true; //ensures all URLs are 'eloqua-ised' and tracked
$email->folderId = FOLDER ID //this is the folder in Eloqua you create to hold the created emails based on the static variables already discovered.
$email->emailGroupId = EMAIL GROUP ID //this is the group in Eloqua you create to hold the created emails based on the static variables
$email->senderEmail = "xxx@yyy.com";
$email->senderName = "My Sender Name";
$email->replyToEmail = "xxx@yyy.com";
$email->replyToName = "My Reply Name";
$email->bounceBackEmail = "xxx@yyy.com";

We now need to hit the API with a create call

$response = $eloquaRequest->post('assets/email', $email);
print_r($response->htmlContent);

Your email has now been created!  Some caveats to be wary of, Eloqua likes well formatted HTML and the API will fail if you provide badly formatted HTML (which you don’t want to do anyway).  Make sure you also stick to UTF-8 encoding to maintain double byte character sets.

We can now do some basic error checking to detect any problems:

$this_email_id = $response->id;    
if(is_numeric($this_email_id)){    
echo '<BR><span style="color:blue;">Made email successfully ID : ' . $this_email_id . 'Make email.  NAME : ' . $email_name . '<br>';    
}else{
echo '<BR><span style="color:red;">Make email FAILED, NAME : ' . $email_name . '</span><br>';    
}

And finally little bit of tidying up.

unset($myHTML);
unset($email);