Search the Omeda Knowledge Base

Email Deployment Content

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-type
a content type supported by this resource. See Supported Content Types for more details. If omitted, the default content type is text/xml.

Supported Content Types

If omitted, the default content type is application/json.

XML
application/xml or text/xml

Supported HTTP Methods

There is one HTTP method supported:

POST
See 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. If you want to use this feature, you will need to contact your Account Manager
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. If you want to use this feature, you will need to contact your Account Manager.
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 string The email address where emails are sent when the recipient clicks ‘Reply’ to the email.
  • – ”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

<?xml version="1.0" encoding="UTF-8"?>
<Deployment>
   <TrackId>FOO020300102</TrackId>
   <UserId>testaccount</UserId>
   <Splits>
	<Split>
          <SplitNumber>1</SplitNumber>
          <FromName><![CDATA[Your Magazine Publisher]]></FromName>
          <Mailbox>publisher</Mailbox>
          <Subject><![CDATA[Renew Today!]]></Subject>
          <ReplyTo>incomingemails@publisher.com</ReplyTo>
          <HtmlContentUrl><![CDATA[https://my.omedastaging.com/portal/verification_test_html.html?param=1&param=2]]></HtmlContentUrl>
          <TextContentUrl><![CDATA[https://my.omedastaging.com/portal/verification_test_text.txt?param=1&param=2]]></TextContentUrl>
        </Split>
	<Split>
           <SplitNumber>2</SplitNumber>
           <FromName><![CDATA[Your Magazine Publisher]]></FromName>
           <Mailbox>publisher</Mailbox>
           <Subject><![CDATA[Renew Now!]]></Subject>
           <ReplyTo>incomingemails@publisher.com</ReplyTo>
           <HtmlContentUrl><![CDATA[https://my.omedastaging.com/portal/verification_test_html2.html?param=3&param=4]]></HtmlContentUrl>
           <TextContentUrl><![CDATA[https://my.omedastaging.com/portal/verification_test_text2.txt?param=3&param=4]]></TextContentUrl>
	</Split>
    </Splits>
</Deployment>

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

<?xml version="1.0" encoding="UTF-8"?>
<ResponseInfo>
   <TrackId>FOO020300102</TrackId>
   <Url>https://ows.omedastaging.com/webservices/rest/brand/FOO/omail/deployment/lookup/FOO0200300112/*</Url>
   <SubmissionId>C95AE90C-BEC6-41F2-91E2-2BA9168D1D1G</SubmissionId>
   <Warnings>
      <Warning>Invalid link found: 'test.cmo'</Warning>
      <Warning>Invalid link found: 'ww.aol.com'</Warning>
      <Warning>Invalid link found: 'link2'</Warning>
      <Warning>Missing Unsubscribe Link for split 1 in HTML</Warning>
   </Warnings>
</ResponseInfo>

Failed Submission

Potential errors:

Invalid xml. Please validate your xml and verify you have used CDATA tags where necessary.
The value '{stringField}' for field '{fieldName}' exceeded a max length of {maximumAllowed}.
The field '{fieldName}' is required.
One of the following fields must be set: 'HtmlContent' or 'TextContent'.
No deployment was found matching trackId '{trackId}'.
Deployment '{trackId}' cannot be edited. Sent, Scheduled , Approved, or Cancelled deployments cannot be edited.
UserId '{userId}' is not authorized to edit deployment '{trackId}'"
Deployment '{trackId}' has been edited from the Omail portal and is not eligible for API access. Last edited by {account} on 2012-02-04 22:15:00.
Deployment '{trackId}'  was created within the Omail portal and is not eligible for API access.
TextContent should not contain html.
HtmlContent must have open and closed html and body tags.

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

<?xml version="1.0" encoding="UTF-8"?>
<ResponseInfo>
   <SubmissionId>C95AE90C-BEC6-41F2-91E2-2BA9168D1D1G</SubmissionId>
   <Errors>
      <Error>'SplitNumber' is a required field.</Error>
      <Error>'FromName' is a required field.</Error>
   </Errors>
</ResponseInfo>

Last Updated On November 30, 2018
Tags:
Knowledge Base Feedback