Email Deployment Content
- Bettina Lippisch
- Robin Heneghan
Summary
The Deployment Content API provides the ability to post information to a deployment. These fields can include the ‘Subject’ line of the email, the ‘From Name’ of the email, the HTML content, the Text content, etc. Since we are passing in html data in this resource, xml is the default format for requests and responses.
An HTTP POST request is used to manage deployment content.
Base Resource URI
For Production, use: https://ows.omeda.com/webservices/rest/brand/{brandAbbreviation}/omail/deployment/content/*
For Testing, use: https://ows.omedastaging.com/webservices/rest/brand/{brandAbbreviation}/omail/deployment/content/*
brandAbbreviation is the abbreviation for the brand to which the data is being posted.
Technical Requirements
The HTTP header must contain the following elements: x-omeda-appid a unique id provided to you by Omeda to access your data. The request will fail without a valid id.content-typea content type supported by this resource. See Supported Content Types for more details. If omitted, the default content type is text/xml.
Any foreign or Unicode characters are used in submission data UTF encoding must be explicitly specified in headers:
Content-type: application/xml; charset=UTF-8Supported Content Types
If omitted, the default content type is application/json.XMLapplication/xml or text/xml
Supported HTTP Methods
There is one HTTP method supported:POSTSee W3C’s POST specs for details.
POST method is used when attaching content to a deployment or updating content.
Field Definition
The following tables describe the hierarchical data elements.
Deployment Elements
It is recommended for certain fields that may contain xml-valid characters, such as Ampersands, that you enclose your data inside a <![CDATA[ ]]> tag. Such characters, if not enclosed in a CDATA tag, result in invalid xml and will return an error response.
Attribute Name | Required? | Data Type | Description |
|---|---|---|---|
UserId | required | string | UserId of the omail account authorized for this deployment. This is generally the ‘OwnerUserId’ specified in the Deployment API. This can also be the ‘Owner’ field returned on the Deployment Search Resource. |
TrackId | required | string | TrackId is the unique tracking number for the deployment the user is updating. |
Splits * | conditional | array | List of attributes for each split if multiple splits are set/updated in one call. If specified none of following attributes should appear at the top level. |
SplitNumber | required | integer | The sequential number of split to be set/updated. The split has its own HTML content, Text content, From Name, etc. |
HtmlContent | conditional | html | The HTML code to assign to the deployment split. |
TextContent | optional | string | The text to assign to the deployment split. |
HtmlContentUrl | conditional | html | The API will pull the html content from the url at the time of the API call and assign it to the deployment. |
TextContentUrl | conditional | string | The API will pull the text content from the url at the time of the API call and assign it to the deployment. |
FromName | conditional: If this element is not passed in with the api call – you must have arranged a default value in Omail Deployment Defaults with your omail representative. | string | The text that the displays in the ‘From’ section of the recipient’s inbox. |
MailBox | conditional: If this element is not passed in with the api call – you must have arranged a default value in Omail Deployment Defaults with your omail representative. | string | The mailbox portion or the handler of the From email address that the recipient will see. If your mailbox is example@abc.com, you would enter example. |
Subject | conditional: If this element is not passed in with the api call – you must have arranged a default value in Omail Deployment Defaults with your omail representative. | string | The subject line of the deployment split. This is what the recipient of the deployment will see in the subject line of the email. |
ReplyTo | optional: If this element is not passed in with the api call, this will be populated by the default value set in Omail Deployment Defaults. | string | The email address where emails are sent when the recipient clicks ‘Reply’ to the email. |
Preheader | optional | string | The short summary text that follows the subject line when viewing an email from the inbox. |
– ”Splits”tag should be used when it’s desired to set/update content for multiple splits in one API call. All following attributes (“SplitNumber” to “ReplyTo”) must be specified for each split then, see examples below.
XML Request Example, single split
<?xml version="1.0" encoding="UTF-8"?>
<Deployment>
<TrackId>FOO020300102</TrackId>
<UserId>testaccount</UserId>
<SplitNumber>1</SplitNumber>
<FromName><![CDATA[Your Magazine Publisher]]></FromName>
<Mailbox>publisher</Mailbox>
<Subject><![CDATA[Renew Today!]]></Subject>
<ReplyTo>incomingemails@publisher.com</ReplyTo>
<HtmlContent><![CDATA[<html><body><h1>Subscriber Today!</h1><div>View Our Offers</div></body></html>]]></HtmlContent>
<TextContent>
<![CDATA[
Subscibe Today!
View Our Offers
]]>
</TextContent>
</Deployment>
XML Request Example using URLs, multiple splits in one call
Response Examples
Responses possible: a successful POST/PUT (200 OK Status) or a failed POST/PUT (400 Bad Request/403 Forbidden/404 Not Found/405 Method Not Allowed Statuses). See W3C’s Status Codes.
Successful Submission
A successful submission will update the deployment content for the request deployment split.
Status | Description |
|---|---|
200 OK | Please be sure to check the response xml for warnings. A typical warning would be an invalid link or a missing unsubscribe link. |
XML Example
Failed Submission
Potential errors:
A failed submission may be due to several factors:
Status | Description |
|---|---|
400 Bad Request | Typically, this error occurs when the request does not follow the specifications. |
403 Forbidden | Typically, this error occurs when the credentials are erroneous. Potentially, an incorrect x-omeda-appid. |
404 Not Found | Typically, this error occurs with a malformed URL or the resource that is searched for is not found. |
405 Method Not Allowed | Typically, this error occurs when the resource accessed is not allowed by the HTTP Method utilized. Make sure you employ the correct HTTP Method (POST) for this request. |
This is not an exhaustive list of errors, but common ones. If an error occurs repeatedly, please contact your Omeda representative.
JSON Example
Table of Contents