Eloqua will soon be exposing our web services in the form of REST Resources. The new API will give users access to create and send emails. It also provides access to manage your emails, edit content and configure details such as the sender, subject and much more. In a previous post, we demonstrated how to Create and Manage Emails using the API. In this post, we’ll describe the various types of email operations
There are two ways to send Email using the API :
- Sending an existing Email to a known Contact (EmailTestDeployment)
- Sending your own content (Email) to a list if known Contacts (EmailInlineDeployment)
(note that you can also send Emails to a group or segment of contacts, but this involves Campaign Canvas workflow. Please see the following post for details).
Both types are derived from the same base : EmailDeployment
public abstract class EmailDeployment { public Email email { get; set; } public DateTime endAt { get; set; } public int? failedSendCount { get; set; } public int? id { get; set; } public string name { get; set; } public string sentSubject { get; set; } public string successfulSendCount { get; set; } public string type { get; set; } }
Note that this is an abstract class and when working with the API, you will need to use either of the following derived types :
- EmailTestDeployment
- EmailInlineDeployment
Let’s look at both types of EmailDeployment in details, starting with EmailInlineDeployments
EmailInlineDeployment
In this scenario, you will send your own custom content to one or many known Contacts. You can avoid having to create and retrieve emails for each operation.
Please note that these endpoints use the same functionality provided by the Engage product, as such you'll need to enable Eloqua Engage access in order to use these endpoints.
The properties on this object are :
public class EmailInlineDeployment : EmailDeployment { public int? clickthroughCount { get; set; } public List<Contact> contacts { get; set; } public int? openCount { get; set; } public int? sendFromUserId { get; set; } }
Let’s look at a sample json request (POST) to create the Deployment.
{ "clickthroughCount": null, "contacts": [ { "emailAddress": "fred.sakr@live.com", "id": 152365 } ], "openCount": null, "sendFromUserId": null, "email": { "htmlContent": { "type": "RawHtmlContent", "html": "<html><head></head><body>sample</body></html>" }, "id": null, "isPlainTextEditable": false, "name": "sample email", "plainText": null, "sendPlainTextOnly": false, "subject": "sample" }, "endAt": "0001-01-01T05:00:00Z", "failedSendCount": null, "name": "sample deployment", "sentSubject": null, "successfulSendCount": null, "type": "EmailInlineDeployment"
}
EmailTestDeployment
In this scenario, you will send an existing Email (already created in Eloqua) to a known Contact. The properties on this object are :
public class EmailTestDeployment : EmailDeployment { public int? contactId { get; set; } public int? sendFromUserId { get; set; } }
Let’s look at a sample json request (POST) to create the Deployment.
{ "contactId": 152365, "sendFromUserId": null, "email": { "bouncebackEmail": null, "emailFooterId": 1, "emailGroupId": 1, "emailHeaderId": 1, "encodingId": 1, "htmlContent": { "type": "RawHtmlContent", "html": "<html><head></head><body>test</body></html>" }, "id": 75, "isPlainTextEditable": false, "name": "sample email", "plainText": "test", "replyToName": "PM -Test", "replyToEmail": "test@test.com", "senderEmail": "test@test.com", "senderName": "PM - Test", "sendPlainTextOnly": false, "subject": "sample" }, "endAt": "0001-01-01T05:00:00Z", "failedSendCount": null, "name": "sample deployment", "sentSubject": null, "successfulSendCount": null, "type": "EmailTestDeployment"
}
As such, the EmailTestDeployment shares all of the properties from the EmailDeployment record, and exposes a ContactId.
The following post includes a complete project and sample code describing how to use the EmailTestDeployments.
Retrieve Deployment Details
You can invoke a GET request to the following endpoint to retrieve details of the deployment :
Where you append the ID of your deployment.
The response will contain details about your deployment, including number of successful sends. See the following json sample for details :
{ "type": "EmailTestDeployment", "currentStatus": "normal", "id": "23", "depth": "complete", "name": "sample deployment", "permissions": "fullControl", "email": {....} "endAt": "1350053861", "failedSendCount": "0", "successfulSendCount": "1", "contactId": "152365"
}
We hope that you find this helpful.
Please note that the code samples referenced here are my own work and something that I've put together to try and help. I'll do my best to support the code, but please understand that this code is not supported by Eloqua.
Thanks,
Fred