Versions Compared

Old Version 1

changes.mady.by.user Bettina Lippisch

Saved on

compared with

New Version 2

changes.mady.by.user Bettina Lippisch

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Live Search
spaceKeyOMEDACLIENTKB
sizelarge
placeholderSearch the Omeda Knowledge Base
typepage

Rw pagetree macro
titleKnowledge Base

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

Code Block
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/*
brandAbbreviationis

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:

Code Block
Content-type: application/xml; charset=UTF-8

Supported 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. 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: 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

Code Block
<?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

Code Block
<?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

Code Block
<?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:

Code Block
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

Code Block
<?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>

Table of Contents

Table of Contents
stylenone