NewsEdge API

Publishing Newsletters

The Publishing APIs allow you to create and share a newsletter via email. Newsletter content may originate from previously saved searches, stories added to folders, text and content marked up with HTML, or any combination of the three. Upload and add images to brand your newsletter with Art APIs. Then publish the newsletter by request or configure a schedule to deliver the newsletter to a list of email addresses.

The list of available APIs is established for each user by the Acquire Media Administrator. (Some documented API may not be available for your use.)

Creating a Newsletter
Previewing your Newsletter
Adding Artwork
Managing Newsletter Recipients.
Sending your Newsletter
Add a Schedule to a Newsletter
Managing Newsletters

Creating a Newsletter

The basic steps to create the newsletter and set up its elements are:

Create the newsletter using newsletter/create
Customize basic newsletter formatting
Add content as separate newsletter sections
Set up email list
Optionally, add art to brand your newsletter

Initial Newsletter Set-up
Setting up Newsletter Sections

Initial Newsletter Set-up

Back to Example

Create the newsletter.
The newsletter/create API request includes the required parameters name and title. The name is for reference only, whereas the title appears at the beginning of your newsletter and is shown in the email subject line.

The API response returns the newsletter unique identifier number which is used in subsequent requests to modify and update the newsletter.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/create?session=935DA0B364E9E130F0EC3827FC3CCC9C&name=Industry+Update&title=Pharmaceutical+Industry+Update
```
Response
```
<opens-api>
  <status>OK</status>
  <newsletter>2104</newsletter>
</opens-api>
```
Modify the newsletter date format and its location.
When the newsletter is published, the current date is shown in the email. A number of different options are available to customize the newsletter date, from where the date is displayed, to how the date is formatted.

By default, the date appears on the same line as the newsletter title, aligned at the right margin, and formatted as YYYYMMDD, e.g. 20190208. In this example, by using the optional parameter dateLocation with the newsletter/update API, the date is set to appear on the line following the title. Appending a second optional parameter dateFormat, set the date format value with necessary punctuation, e.g. forward slash (/), pipe-delimiter (|), hyphen (-), or comma (,), to modify the format of the date. In this example, the date will be changed to display as February 8, 2019.

<%a> - Day of the week written in short form, e.g. Mon, Tue, Wed, etc.

<%A> - Day of the week written in long form, e.g. Monday, Tuesday, Wednesday, etc.

<%_m> - Month expressed in single digit numeric form, e.g. 1 for January, 2 for February, ..., through to 12 for December.

<%m> - Month expressed in double digit numeric form, e.g. 01 for January, 02 for February, ..., through to 12 for December.

<%b> - Month written in short form, e.g. Jan, Feb, Mar, etc.

<%B> - Month written in long form, e.g. January, February, March, etc.

<%e> - Day of month expressed in single digit numeric form, e.g. 1, 2, 3, ..., 30, 31.

<%d> - Day of month expressed in double digits numeric form, e.g. 01, 02, 03, ..., 30, 31.

<%ord> - Include ordinal after the day of month, e.g. st after the 1st, nd after the 2nd, etc.

<%y> - Year in double digit numeric form, e.g. 18 for 2018, 19 for 2019, etc.

<%Y> - Year in four digit numeric form, e.g. 2018, 2019, etc.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/update?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&dateLocation=FOLLOW&dateFormat=<%B>%20<%e>,%20<%Y>
```
Response
```
<opens-api>
  <status>OK</status>
  <newsletter>2104</newsletter>
</opens-api>
```

Retrieve newsletter details to confirm changes.

At any time, use the newsletter/info request, with the newsletter parameter and the newsletter identifier returned from the newsletter/create request, to review the set up of your newsletter.

Request

https://secure.newsedge.com/opensapi/20/newsletter/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>OK</status>
  <newsletter id="2104" name="Industry Update" desc="" enableAutoPublish="FALSE" enableHighlighting="TRUE" tocFormat="HEADLINE" storyFormat="BRIEF" level="USER" permission="WRITE"> 
    <topArt id="" name="" link=""/>
    <title>Pharmaceutical Industry Update</title>
    <dateFormat location="FOLLOW"><%B> <%e>, <%Y></dateFormat>
    <includePagetop>TRUE</includePagetop>
    <dateSubject>TRUE</dateSubject>
    <introduction/>
    <tocComment/>
    <lastExecTime/>
    <sections count="0"></sections>
    <schedules count="0"></schedules>
    <bottomArt id="" name="" link=""/>
    <footer/>
  </newsletter>
</opens-api>

Add an introduction.

A brief introduction at the beginning of the newsletter can be used to highlight important articles, add an announcement, or provide your contact information to readers. The introduction text may be up to 2,500 characters long and should be URL encoded.

In this example, use the newsletter/update with the optional parameter introduction to add the introductory text.

Request

https://secure.newsedge.com/opensapi/20/newsletter/update?session=935DA0B364E9E130F0EC3827F&newsletter=2104&introduction=%3Cp%3EIn+the+newsletter+today+are+some+top+stories+about+our+competitors+and+their+new+products+at+this+year%27s+annual+trade+show.+%3C%2Fp%3E%0D%0A%0D%0A%3Cp%3EIf+you+have+any+news+to+share+with+the+rest+of+the+company%2C+please+forward+your+items+to+Jane+Doe%2C+%3Ca+href%3D%22mailto%3Ajdoe%40mycompany.com%3Fsubject%3DPharmaceutical%2520News%2520Update%22%3Ejdoe%40mycompany.com%3C%2Fa%3E.%3C%2Fp%3E

Response

<opens-api>
  <status>OK</status>
</opens-api>

Formatting the Table of Contents and newsletter contents.
When the newsletter is initially created, the Table of Contents is set to show section names with headlines and newsletter section content as headline plus summary. In this example, using newsletter/update again, the Table of Contents will be modified to include only the section names by appending the optional parameter tocFormat, and the newsletter body, to show only headlines by appending the optional parameter storyFormat.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/update?session=935DA0B364E9E130F0EC3827F&newsletter=2104&tocFormat=SECTION&storyFormat=HEADLINE
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Retrieve newsletter details to confirm changes.

Request

https://secure.newsedge.com/opensapi/20/newsletter/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>OK</status>
  <newsletter id="2104" name="Industry Update" desc="" enableAutoPublish="FALSE" enableHighlighting="TRUE" tocFormat="SECTION" storyFormat="HEADLINE" level="USER" permission="WRITE">
  <topArt id="" name="" link=""/>
  <title>Pharmaceutical Industry Update</title>
  <dateFormat location="FOLLOW"><%B> <%e>, <%Y></dateFormat>
    <includePagetop>TRUE</includePagetop>
    <dateSubject>TRUE</dateSubject>
    <introduction><p>In the newsletter today are some top stories about our competitors and their new products at this year's annual trade show. </p>
    <p>If you have any news to share with the rest of the company, please forward your items to Jane Doe, <a href="mailto:jdoe@mycompany.com?subject=Pharmaceutical%20News%20Update">jdoe@mycompany.com</a>.</p></introduction>
    <tocComment/>
    <lastExecTime/>
    <sections count="0"></sections>
    <schedules count="0"></schedules>
    <bottomArt id="" name="" link=""/>
    <footer/>
  </newsletter>
</opens-api>

Setting up Newsletter Sections

Back to Example

Each section of the newsletter can be populated by any one of these three different source types:

Saved search - Use the savedsearch/list API to retrieve available saved searches and identify the desired search ID. With the newsletter/addsection request, use the required parameter dataSourceType with value SEARCH and include the optional parameter search along with the search ID value.
Story folder - Use the storyfolder/list API to retrieve available folders and identify the ID for the desired folder. Then with the newsletter/addsection, use required parameter dataSourceType with value FOLDER and append the optional parameter folder with the folder ID.
HTML - use HTML mark-up to add content to the section. An HTML based section can be left empty, or use the optional parameter html to define the HTML mark-up. With the newsletter/addsection required parameter dataSourceType, submit the value HTML.

The first two source types populates a newsletter section with headline contents. The HTML option allows you to add informational content, such as an announcement, information and links to industry resources that may be of interest to your readers, etc.

In the following examples, three newsletter sections will be added. The first section will link to stories resulting from a saved search. The second section will link to stories saved to a folder. Finally, in the last section, the section will be used to display a message for the newsletter readers.

Determining the saved search for the newsletter section.

Submit a request with the savedsearch/list API to retrieve available saved searches.

Request

https://secure.newsedge.com/opensapi/20/savedsearch/list?session=935DA0B364E9E130F0EC3827FC3CCC9C

Response

<opens-api>
  <status>OK</status>
  <savedsearches>
    <savedsearch ss="13819" owner="API User" level="PERSONAL" name="Drug Trials" permission="WRITE"/>
    <savedsearch ss="13821" owner="API User" level="PERSONAL" name="Patent and Market News" permission="WRITE"/>
    <savedsearch ss="13822" owner="API User" level="PERSONAL" name="Weekly Pfizer Report" permission="WRITE"/>
    . . .
  </savedsearches>
</opens-api>

Creating a section.
To add a newsletter section, use the newsletter/addsection along with parameters to name the section, define the dataSourceType as one of the three content options, and the requisite optional parameter based on the data type. In this example, the first section in our newsletter will get its content from a saved search.

Note the section ID number which is referenced when making additional configuration changes.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/addsection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&name=Recent%20Patent%20News&dataSourceType=SEARCH&search=13821
```
Response
```
<opens-api>
  <status>OK</status>
  <sectionID>3455</sectionID>
</opens-api>
```
Customizing the section.
Once the section is created and content linked, consider other section configurations, e.g. the number of headlines to display defaults to 10, should there be more or fewer headlines? When there are no results from the search, the newsletter omits the section, should the section be included even when no results are found? Do you want to add a section comment. Review the optional parameters for newsletter/updatesection to determine whether to customize further.

In this example, the number of headlines will be changed to 15 by using the newsletter/updatesection API and the optional parameter storyLimit.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/updatesection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&section=3455&storyLimit=15
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Reviewing the section configuration.

Use the newsletter/getsection API to review the section details.

Note the section is linked to data source type SEARCH, which is identified by the savedsearch attribute within the section element. In this response the dataSourceName attribute represents the saved search name.

Request

https://secure.newsedge.com/opensapi/20/newsletter/getsection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&section=3455

Response

<opens-api>
  <status>OK</status>
  <section id="3455" order="1" name="Recent Patent News" storyLimit="15" dataSourceType="SEARCH" storyfolder="" savedsearch="13821" sectionHtml="" comment="" storeOnSend="FALSE" dataSourceName="Patent and Market News" sendEmptySection="FALSE" emptySectionMessage=""/>
</opens-api>

Selecting a folder for the next section.

For the next section of the newsletter, the content will come from a story folder. Use the storyfolder/list API to retrieve the list of folders.

Request

https://secure.newsedge.com/opensapi/20/storyfolder/list?session=935DA0B364E9E130F0EC3827FC3CCC9C

Response

<opens-api>
  <status>OK</status>
  <storyfolders count="4">
    <storyfolder id="17786" order="3" count="0" sharing="" name="Industry News" description="Industry News" owner="API User" level="USER" permission="READ|WRITE|MANAGE" orderBy="RANK"/>
    <storyfolder id="17791" order="2" count="0" sharing="" name="My Stories" description="Stories for my homepage" owner="API User" level="USER" permission="READ|WRITE|MANAGE" orderBy="PUBDATE"/>
    <storyfolder id="17785" order="1" count="0" sharing="" name="My Stories manual fill TEST" description="" owner="API User" level="USER" permission="READ|WRITE|MANAGE" orderBy="DATEADDED"/>
  </storyfolders>
</opens-api>

Adding section linked to a folder.
From the folder results above, the new section will be linked to the Industry News folder contents, ID 17786. Using the newsletter/addsection API, include parameters dataSourceType with value FOLDER and this time, add the optional parameter folder with the ID value.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/addsection?session=9E10D3DB0DE88EB80530C8578EF261AF&newsletter=2104&name=Industry%20News&dataSourceType=FOLDER&folder=17786
```
Response
```
<opens-api>
  <status>OK</status>
  <sectionID>3456</sectionID>
</opens-api>
```
Customizing folder-linked section.
Folders contain selected stories and only the stories with a status of ACTIVE will be published in the newsletter. To avoid publishing the same folder articles in the next edition, use the optional parameter storeOnSend with the newsletter/updatesection API to change the story status to STORED after publication.

To learn more about story status, see the storyfolder/updatestory API optional parameter status.

In this example, the section will display up to 15 ACTIVE stories from the folder and after the newsletter is published, the status for published stories will be changed to STORED.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/updatesection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&section=3456&storeOnSend=TRUE&storyLimit=15
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>          
        
```

Reviewing the section configuration.

Use the newsletter/getsection API to review the section details.

Note the section is linked to data source type FOLDER, and the name of the folder mentioned as the dataSourceName. The storeOnSend attribute is TRUE which means stories in the folder will be modified from ACTIVE to STORED once the newsletter is published.

Request

https://secure.newsedge.com/opensapi/20/newsletter/getsection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&section=3456

Response

<opens-api>
  <status>OK</status>
  <section id="3456" order="2" name="Industry News" storyLimit="15" dataSourceType="FOLDER" storyfolder="17778" savedsearch="" sectionHtml="" comment="" storeOnSend="TRUE" dataSourceName="Industry News" sendEmptySection="FALSE" emptySectionMessage=""/>
</opens-api>

Sorting sections.
As each section is added to the newsletter the section is assigned an order value one integer greater than the previous section. The first "Patent News" section has order value "1" and is shown first in the newsletter. The second "Industry News" section has order value "2" and it will appear following the Patent News. Here, in this example, the order of the sections will be changed to have Industry News stories appearing before Patent News. Use the newsletter/updatesection with the optional parameter order.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/updatesection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&section=3456&order=1
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>          
        
```

Review the newsletter.

Use the newsletter/info request to retrieve the newsletter configuration and sections.

Request

https://secure.newsedge.com/opensapi/20/newsletter/getsection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>OK</status>
  <newsletter id="2104" name="Industry Update" desc="" enableAutoPublish="FALSE" enableHighlighting="TRUE" tocFormat="SECTION" storyFormat="HEADLINE" level="USER" permission="WRITE">
    <topArt id="" name="" link=""/>
    <title>Pharmaceutical Industry Update</title>
    <dateFormat location="FOLLOW"><%B> <%e>, <%Y></dateFormat>
    <includePagetop>TRUE</includePagetop>
    <dateSubject>TRUE</dateSubject>
    <introduction>
      <p>In the newsletter today are some top stories about our competitors and their new products at this year's annual trade show. </p>

      <p>If you have any news to share with the rest of the company, please forward your items to Jane Doe, <a href="mailto:jdoe@mycompany.com?subject=Pharmaceutical%20News%20Update">jdoe@mycompany.com</a>.</p>
    </introduction>
    <tocComment/>
    <lastExecTime/>
    <sections count="2">
      <section id="3456"/>
      <section id="3455"/>
    </sections>
    <schedules count="0"></schedules>
    <bottomArt id="" name="" link=""/>
    <footer/>
  </newsletter>
</opens-api>

Add a section with content formatted as HTML.
Aside from displaying news results in a section, you may create a section composed of a message formatted in HTML. (Remember to URL-encode the HTML.) In this example, the new section will use HTML as its dateSourceType. The HTML can be included in this newsletter/addsection request or can be defined later using the newsletter/updatesection API.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/addsection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&name=What's%20New%20at%20Our%20Company&dataSourceType=HTML
```
Response
```
<opens-api>
  <status>OK</status>
  <sectionID>3467</sectionID>
</opens-api>
```

Updating section HTML.

Using the newsletter/updatesection API with the following parameters newsletter, section, dataSourceType and html, where the html value is a message marked up as HTML and it is url-encoded.

Request

https://secure.newsedge.com/opensapi/20/newsletter/updatesection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&section=3467&dataSourceType=html&html=%3Ctable%20width%3D%22100%25%22%20bgcolor%3D%22%23cccccc%22%20style%3D%22font-family%3Aarial%3B%20font-size%3A12px%22%3E%3Ctr%3E%3Ctd%20colspan%3D%222%22%3E%3Cb%3EJoin%20us%20at%20the%20following%20trade%20shows%3C%2FBI%3E%3C%2Ftd%3E%3C%2Ftr%3E%20%3Ctr%3E%3Ctd%20width%3D%2225%25%22%3EMay%201%2C%202019%2C%20Miami%2C%20FL%3C%2Ftd%3E%3Ctd%20width%3D%2275%25%22%3E%3Cb%3EBiotech%20Industry%20Show%3C%2FBI%3E%3C%2Ftd%3E%3C%2Ftr%3E%20%3Ctr%3E%3Ctd%20width%3D%2225%25%22%3EMay%2015%2C%202019%2C%20London%2C%20UK%3C%2Ftd%3E%3Ctd%20width%3D%2275%25%22%3E%3Cb%3EPharma%20CI%20Show%3C%2FBI%3E%3C%2Ftd%3E%3C%2Ftr%3E%20%3C%2Ftable%3E

Response

<opens-api>
  <status>OK</status>
</opens-api>

Reviewing the section configuration.

In the results, note the dataSourceType is HTML and the sectionHTML is the message marked up as an HTML table.

Request

https://secure.newsedge.com/opensapi/20/newsletter/getsection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&section=3467

Response

<opens-api>
  <status>OK</status>
  <section id="3467" order="4" name="What's New at Our Company" storyLimit="10"   dataSourceType="HTML" storyfolder="" savedsearch="" sectionHtml="<table width="100%" bgcolor="#cccccc" style="font-family:arial; font-size:12px"><tr><td colspan="2"><b>Join us at the following trade shows</b></td></tr> <tr><td width="25%">May 1, 2019, Miami, FL</td><td width="75%"><b>Biotech Industry Show</b></td></tr> <tr><td width="25%">May 15, 2019, London, UK</td><td width="75%"><b>Pharma CI Show</b></td></tr> </table>" comment="" storeOnSend="FALSE" dataSourceName="" sendEmptySection="FALSE" emptySectionMessage=""/>
</opens-api>

Reordering the HTML section.
Adjust the sections so the HTML section appears after the first news section and before the second news section, using the order parameter with the newsletter and section parameters.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/updatesection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&section=3467&order=2
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Review the newsletter configuration.

Request

https://secure.newsedge.com/opensapi/20/newsletter/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>OK</status>
  <newsletter id="2104" name="Industry Update" desc="" enableAutoPublish="FALSE" enableHighlighting="TRUE" tocFormat="SECTION" storyFormat="HEADLINE" level="USER" permission="WRITE">
    <topArt id="" name="" link=""/>
    <title>Pharmaceutical Industry Update</title>
    <dateFormat location="FOLLOW"><%B> <%e>, <%Y></dateFormat>
    <includePagetop>TRUE</includePagetop>
    <dateSubject>TRUE</dateSubject>
    <introduction><p>In the newsletter today are some top stories about our competitors and their new products at this year's annual trade show. </p>
<p>If you have any news to share with the rest of the company, please forward your items to Jane Doe, <a href="mailto:jdoe@mycompany.com?subject=Pharmaceutical%20News%20Update">jdoe@mycompany.com</a>.</p></introduction>
    <tocComment/>
    <lastExecTime/>
    <sections count="4">
      <section id="3456"/>
      <section id="3467"/>
      <section id="3455"/>
      <section id="3458"/>
    </sections>
    <schedules count="0"></schedules>
    <bottomArt id="" name="" link=""/>
    <footer/>
  </newsletter>
</opens-api>

Deleting a section.

The newsletter/delete API is used along with the newsletter and section parameters to permanentlyy delete a section of the newsletter.

Request

https://secure.newsedge.com/opensapi/20/newsletter/deletesection?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&section=3458

Response

<opens-api>
  <status>OK</status>
</opens-api>

Previewing your Newsletter

The newsletter/preview API is used in conjunction with the newsletter/checkpreview API to obtain a URL that displays the newsletter as it would look when emailed.

Get key to preview the newsletter.

With the newsletter/preview API, a key is returned and will be used in the next step to check whether the newsletter is ready for preview.

Request

https://secure.newsedge.com/opensapi/20/newsletter/preview?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

    <opens-api>
      <status>PENDING</status>
      <key>32966_20190501154206</key>
    </opens-api>

Check if the preview is ready.
Use the newsletter/checkpreview API with the key from the previous response to obtain a URL. The URL returns an HTML preview of your newsletter as it would look when emailed to your newsletter recipients.

After previewing the newsletter, you may decide to modify the newsletter using newsletter/update or newsletter/updatesection. If you wish to add some images to the top of the newsletter, or at the end, you will want to continue to the next set of examples for adding artwork. If you do not wish to add any artwork, skip to the example further down to learn how to add newsletter recipients.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/checkpreview?session=935DA0B364E9E130F0EC3827FC3CCC9C&key=32966_20190501154206
```
Response
```
<opens-api>
  <status>OK</status>
  <url>https://secure.newsedge.com/newsletterpreview/newsletter_32966_20190501154206.html</url>
</opens-api>
```

Adding Artwork

Add visual interest to your newsletter by including an image at the beginning or end of the newsletter, as part of the introduction or footer, or include an image with the HTML-defined sections. The Art APIs allow you to upload, manage and delete images. Once the art is uploaded, use the newsletter/addtopart or newsletter/addbottomart to include images as the newsletter masthead or at the end of your newsletter. Or use the optional parameters with the newsletter/update and newsletter/updatesection APIs to link the images with the introduction, footer or section(s).

Note, images can be used multiple times, within the same newsletter or for different newsletters, e.g. upload a company logo and reuse this logo as the art shown at the top of all your newsletters.

Uploading, managing and deleting art
Adding art to a Newsletter

Uploading, managing and deleting art

Back to Example

Upload an image.
Use the art/upload API with the parameter name to create a named image and to upload the image for use with your newsletter. You will want to use an HTTP Post command to upload the image.

Before uploading the image, determine the suitable image size for your newsletter. The API will not re-size the image. Supported image file formats include .jpg, .jpeg, .png, .gif, and .bmp.

The returned results is a unique identifier artId that is to be used with other newsletter API calls link the image to the newsletter. The artLink URL can be used to preview the image and is embedded in the newsletter as the image source.

Request
```
https://secure.newsedge.com/opensapi/20/art/upload?session=935DA0B364E9E130F0EC3827FC3CCC9C&name=Globe%20with%20dotted%20overlay
```
Response
```
<?xml version="1.0" encoding="UTF-8"?>
<opens-api>
<status>OK</status>
<artId>868</artId>
<artLink>https://secure.newsedge.com/art/32966_USER_20190129091338004.jpg</artLink>
</opens-api>
```

Get list of uploaded images.

Request

https://secure.newsedge.com/opensapi/20/art/list?session=935DA0B364E9E130F0EC3827FC3CCC9C

Response

<opens-api>
  <status>OK</status>
  <artList>
    <art id="868" name="Globe with dotted overlay" level="USER" permission="WRITE" link="https://secure.newsedge.com/art/32966_USER_20190129091338004.jpg" desc="Sample" createdBy="API User" modifiedBy="API User" modifiedOn="20190506T114013-0400"/>
    <art id="867" name="Newscycle" level="USER" permission="WRITE" link="https://secure.newsedge.com/art/32966_USER_20190129091310642.png" desc="Logo with keyboard image" createdBy="API User" modifiedBy="API User" modifiedOn="20190129T091058-0500"/>
    <art id="876" name="NewsEdge light" level="USER" permission="WRITE" link="https://secure.newsedge.com/art/32966_USER_20190520134258415.png" desc="midnight NewsEdge cream" createdBy="API User" modifiedBy="API User" modifiedOn="20190520T134301-0400"/>
  </artList>
</opens-api>

Delete an image.
With the art id value returned from the art/upload or art/list response, make a request to delete the image.

Deleting the image also removes any newsletter references to the image. So if a newsletter was previously published using this art, your readers will see a broken image when re-reading older newsletters.

Request
```
https://secure.newsedge.com/opensapi/20/art/delete?session=935DA0B364E9E130F0EC3827FC3CCC9C&art=867
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Adding art to a Newsletter

Back to Example

Now that the images have been uploaded to the system, use the artwork as the banner at the top or end of your newsletter, or as part of the comment fields, like the newsletter introduction, section comments or footer.

Get a list of available art.

Use the art/list API to retrieve the images and note the id for the image to be used for your newsletter.

Request

https://secure.newsedge.com/opensapi/20/art/list?session=935DA0B364E9E130F0EC3827FC3CCC9C

Response

<opens-api>
  <status>OK</status>
  <artList>
    <art id="868" name="Globe with dotted overlay" level="USER" permission="WRITE" link="https://secure.newsedge.com/art/32966_USER_20190129091338004.jpg" desc="Sample" createdBy="API User" modifiedBy="API User" modifiedOn="20190506T114013-0400"/>
    <art id="876" name="NewsEdge light" level="USER" permission="WRITE" link="https://secure.newsedge.com/art/32966_USER_20190520134258415.png" desc="midnight NewsEdge cream" createdBy="API User" modifiedBy="API User" modifiedOn="20190520T134301-0400"/>
  </artList>
</opens-api>

Add the image to your newsletter.
The newsletter/addtopart and newsletter/addbottomart APIs are used to add the image to the top or end of your newsletter, respectively. If you like, the image can be added at the top and the end, by submitting a request with each API using the same art id. In this example, the art will be added as the opening image for your newsletter. If necessary, use the newsletter/list API to obtain the newsletter id.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/addtopart?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&art=868
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Add image at the end of the newsletter

Request

https://secure.newsedge.com/opensapi/20/newsletter/addbottomart?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&art=876

Response

<opens-api>
  <status>OK</status>
</opens-api>

Get key to preview the newsletter.
The newsletter/preview API is used in conjunction with the newsletter/checkpreview API to obtain a URL for an HTML version of the newsletter. In this example, get the key to generate the URL.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/preview?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104
```
Response
```
<opens-api>
  <status>PENDING</status>
  <key>32966_20190520135840</key>
</opens-api>
```
Get newsletter preview URL.
With the preview, you can check the size of the images used at the top or end of the newsletter for size, whether it is too small or too large. NewsEdge does not resize the uploaded images, so to change the size of the image, delete and upload a new image.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/checkpreview?session=935DA0B364E9E130F0EC3827FC3CCC9C&key=32966_20190520135840
```
Response
```
<opens-api>
  <status>OK</status>
  <url>https://secure.newsedge.com/newsletterpreview/newsletter_32966_20190520135840.html</url>
</opens-api>
```

Get newsletter info.

Another way to check that the art has been added to the newsletter is to request the newsletter/info results. The image URL for top art and bottom art will be returned when images are linked to the newsletter. Note: reviewing the newsletter with the newsletter/info API does not show the size of the image relative to the newsletter. The best way to confirm the image size is to preview the newsletter, as described by the previous two examples.

Request

https://secure.newsedge.com/opensapi/20/newsletter/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>OK</status>
  <newsletter id="2104" name="Industry Update" desc="" enableAutoPublish="FALSE" enableHighlighting="TRUE" tocFormat="SECTION" storyFormat="HEADLINE" level="USER" permission="WRITE">
    <topArt id="868" name="Globe with dotted overlay" link="https://secure.newsedge.com/art/32966_USER_20190129091338004.jpg"/>
    <title>Pharmaceutical Industry Update</title>
    <dateFormat location="FOLLOW"><%B> <%e>, <%Y></dateFormat>
    <includePagetop>TRUE</includePagetop>
    <dateSubject>TRUE</dateSubject>
    <introduction>
      <p>In the newsletter today are some top stories about our competitors and their new products at this year's annual trade show. </p> 
      <p>If you have any news to share with the rest of the company, please forward your items to Jane Doe, <a href="mailto:jdoe@mycompany.com?subject=Pharmaceutical%20News%20Update">jdoe@mycompany.com</a>.</p></introduction>
    <tocComment/>
    <lastExecTime/>
    <sections count="3">
      <section id="3456"/>
      <section id="3467"/>
      <section id="3455"/>
    </sections>
    <schedules count="0"></schedules>
    <bottomArt id="876" name="NewsEdge light" link="https://secure.newsedge.com/art/32966_USER_20190520134258415.png"/>
    <footer/>
  </newsletter>
</opens-api>

Managing Newsletter Recipients.

Newsletters are sent via email to one or more email addresses. Use the Email List APIs to manage your newsletter recipients.

Adding an email recipient.
Submit a newsletter/addemail request with the emailAddress parameter to associate one email address as a recipient. Make additional requests to add more email recipients.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/addemail?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&emailAddress=msmith@mycompany.com
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Retrieve the list of newsletter recipients.

Use the newsletter/getemaillist API to request all email addresses configured as recipients for the newsletter.

If the response to this request is an error "Invalid Distlistid" this means there are no email recipients configured to receive this newsletter and you can use the newsletter/addemail request to associate an email address.

 <opens-api>
 <status>ERROR</status>
 <error>INVALID DISTLISTID</error>
 </opens-api>

Request

https://secure.newsedge.com/opensapi/20/newsletter/getemaillist?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>OK</status>
  <emailList name="Destination list for Industry Update (2104)" desc="">
    <email firstName="" lastName="" email="msmith@mycompany.com" status="ACTIVE"/>
    <email firstName="" lastName="" email="alee@mcompany.com" status="ACTIVE"/>
  </emailList>
</opens-api>

Delete an email recipient.
To remove an email address from the recipients list use newsletter/deleteemail API with the parameter emailAddress. If an email address is misspelled, delete the email address and re-add the correct email using another newsletter/addemail request.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/deleteemail?session=F807924B89CBEA15C12589D14A9E263D&newsletter=2104&emailAddress=alee@mcompany.com
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Sending your Newsletter

Use the newsletter/send API to assemble the newsletter elements (artwork, title, date, formatting, sections, stories, footer etc.) and to publish the entire newsletter to the associated email addresses. The returned result is a key element which may be used with newsletter/checksend to confirm if the newsletter has been sent. If the status of the newsletter/checksend is PENDING, and you wish to cancel this action, use the newsletter/cancelsend API.

Requesting the newsletter send key.

In this example, the newsletter/send API will return a numeric key for use with the subsequent newsletter/checksend API.

Request

https://secure.newsedge.com/opensapi/20/newsletter/send?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>PENDING</status>
  <key>32966_20190520151155</key>
</opens-api>

Check if newsletter has been sent.
Use the newsletter/checksend API with the key returned in the previous response. When the status is OK, this means the newsletter has been sent. If the status is PENDING, it means NewsEdge is still preparing the newsletter. If the status is ERROR, a descriptive error message will be presented for further action.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/checksend?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&key=32966_20190520151155
```
Response
```
<opens-api>
  <status>OK</status>
  <email-status>OK</email-status>
</opens-api>
```
Cancel sending newsletter.
If the status returned with newsletter/send and newsletter/checksend is PENDING, you may use the newsletter/cancelsend API with the key value to stop NewsEdge from publishing the newsletter to your email recipients.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/cancelsend?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&key=32966_20190520155534
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Add a Schedule to a Newsletter

As an alternative to sending a newsletter by issuing the newsletter/send request, the OPENS API offers the option for a newsletter to be scheduled and automatically published on a predetermined day(s) of the week at a set time(s) of day or at intervals throughout the day.

The OPENS API user's timezone defaults to Eastern Time. Please contact the Acquire Media Administrator for assistance to modify the default timezone.

Newsletter Schedule at a Specified Time
Add a Periodic Schedule to a Newsletter

Newsletter Schedule at a Specified Time

Back to Example

With this example, the newsletter will be set to publish at a set time.

Add a schedule.
In this example, the newsletter will be configured to automatically publish on Monday and Thursdays at 8:00 AM.

With the newsletter/addschedule API, use the following required parameters:
- type - with the value settime.
- days - with the values for the days of the week.
- setTime - with the time of day entered as hhmmss. This time is set per the timezone assigned to your OPENS API account. To modify the default timezone, contact the Acquire Media Administrator.
For the days values, each day can be represented by a numeric value, e.g. 1 for Monday, 2 for Tuesday, through to 7 for Sunday, or alternatively, spell out the day(s) of the week in full. Use a comma to separate values when setting the schedule to publish on multiple days of the week. Use weekdays as a value if setting the newsletter to auto-publish from Monday through to Friday. And use all as the value if the newsletter is to publish every day of the week.

The returned result is a schedule ID used to retrieve the schedule details with the newsletter/getschedule API.

Note: after adding the schedule, to begin automatically publishing the newsletter, you will need to update the newsletter to enable auto-publishing. See the Activate Newsletter example further down.
Request
```
https://secure.newsedge.com/opensapi/20/newsletter/addschedule?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&days=1,4&type=settime&setTime=080000
```
Response
```
<opens-api>
  <status>OK</status>
  <scheduleID>400</scheduleID>
</opens-api>
```

Review the newsletter details.

In the newsletter/info returned results, there is one schedule associated to this newsletter. If you would like to publish this newsletter at a different time on other days of the week, a second schedule can be added by submitting another newsletter/addschedule API request.

Request

https://secure.newsedge.com/opensapi/20/newsletter/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>OK</status>
  <newsletter id="2104" name="Industry Update" desc="" enableAutoPublish="FALSE" enableHighlighting="TRUE" tocFormat="SECTION" storyFormat="HEADLINE" level="USER" permission="WRITE">
    <topArt id="868" name="Globe with dotted overlay" link="https://secure.newsedge.com/art/32966_USER_20190129091338004.jpg"/>
    <title>Pharmaceutical Industry Update</title>
    <dateFormat location="FOLLOW"><%B> <%e>, <%Y></dateFormat>
    <includePagetop>TRUE</includePagetop>
    <dateSubject>TRUE</dateSubject>
    <introduction><p>In the newsletter today are some top stories about our competitors and their new products at this year's annual trade show. </p><p>If you have any news to share with the rest of the company, please forward your items to Jane Doe, <a href="mailto:jdoe@mycompany.com?subject=Pharmaceutical%20News%20Update">jdoe@mycompany.com</a>.</p></introduction>
    <tocComment/>
    <lastExecTime>20190520T160927-0400</lastExecTime>
    <sections count="3">
      <section id="3456"/>
      <section id="3467"/>
      <section id="3455"/>
    </sections>
    <schedules count="1">
      <schedule id="400"/>
    </schedules>
    <bottomArt id="876" name="NewsEdge light" link="https://secure.newsedge.com/art/32966_USER_20190520134258415.png"/>
    <footer/>
  </newsletter>
</opens-api>

Get schedule details.

In this example, use the newsletter/getschedule API with the schedule ID returned in the newsletter/addschedule or newsletter/info results to retrieve the details.

Request

https://secure.newsedge.com/opensapi/20/newsletter/getschedule?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&schedule=400

Response

<opens-api>
  <status>OK</status>
  <schedule id="400 ">
    <dayOfWeek number="1,4">
      <setTime>T080000-0500</setTime>
    </dayOfWeek>
  </schedule>
</opens-api>

Activate the newsletter.
Once the newsletter schedule is configured, you may begin the delivery by using the newsletter/update API with the parameter enableAutoPublish set to TRUE.

At the designated time, the system will gather the stories for each newsletter section, depending on the section configurations, it will check for new search results since the last time the newsletter was published or look for ACTIVE stories in the story folders, and send the newsletter to the associated email recipients.

Note: If there are no new search results and no ACTIVE stories in the folders, then an empty newsletter is not published. Unless, one or more sections was configured to show a message with an empty section.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/update?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&enableAutoPublish=TRUE
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```

Confirm the newsletter is set to auto-publish.

In the newsletter/info returned results, note that the newsletter element has its attribute enableAutoPublish set to TRUE.

Request

https://secure.newsedge.com/opensapi/20/newsletter/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>OK</status>
  <newsletter id="2104" name="Industry Update" desc="" enableAutoPublish="TRUE" enableHighlighting="TRUE" tocFormat="SECTION" storyFormat="HEADLINE" level="USER" permission="WRITE">
    <topArt id="868" name="Globe with dotted overlay" link="https://secure.newsedge.com/art/32966_USER_20190129091338004.jpg"/>
    <title>Pharmaceutical Industry Update</title>
    <dateFormat location="FOLLOW"><%B> <%e>, <%Y></dateFormat>
    <includePagetop>TRUE</includePagetop>
    <dateSubject>TRUE</dateSubject>
    <introduction><p>In the newsletter today are some top stories about our competitors and their new products at this year's annual trade show. </p><p>If you have any news to share with the rest of the company, please forward your items to Jane Doe, <a href="mailto:jdoe@mycompany.com?subject=Pharmaceutical%20News%20Update">jdoe@mycompany.com</a>.</p></introduction>
    <tocComment/>
    <lastExecTime>20190520T160927-0400</lastExecTime>
    <sections count="3">
      <section id="3456"/>
      <section id="3467"/>
      <section id="3455"/>
    </sections>
    <schedules count="1">
      <schedule id="400"/>
    </schedules>
    <bottomArt id="876" name="NewsEdge light" link="https://secure.newsedge.com/art/32966_USER_20190520134258415.png"/>
    <footer/>
  </newsletter>
</opens-api>

Pause the auto-publishing.

To place a hold on automatically publishing the newsletter, use the newsletter/update API with the enableAutoPublish with the value as FALSE.

Request

https://secure.newsedge.com/opensapi/20/newsletter/update?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&enableAutoPublish=FALSE

Response

<opens-api>
  <status>OK</status>
</opens-api>

Delete a schedule.

To permanently remove the schedule from the newsletter configuration, with the newsletter ID and schedule ID, submit a newsletter/deleteschedule request.

Request

https://secure.newsedge.com/opensapi/20/newsletter/deleteschedule?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&schedule=400

Response

<opens-api>
  <status>OK</status>
</opens-api>

Add a Periodic Schedule to a Newsletter

Back to Example

An alternative to setting specific times for the newsletter to publish is set a newsletter to publish at regular time intervals, e.g. every 15, 30 or 60 minutes.

Add a periodic schedule.
In contrast to the newsletter/addschedule example above, the newsletter/addschedule request here uses the following required parameters:
- type - with the value periodic.
- days - with the values for the days of the week separated by commas. The value for Monday through Friday is weekdays. The value for 7-days a week is all.
- startTime - the time of day when the schedule will take effect, and with value submitted as hhmmss. This time is set per the timezone assigned to your OPENS API account. To modify the default timezone, contact the Acquire Media Administrator.
- endTime - the time of day the newsletter will cease automatically publishing and value submitted as hhmmss.
- periodInSeconds - time interval specified in seconds. e.g. 1800 would schedule the newsletter to send every 30 minutes.
In this example, the newsletter will be configured to automatically publish on Mondays and Thursdays, every 30 minutes beginning at 8:00 AM and ending at 5:00PM. Remember, the default timezone is Eastern Time. Please contact the Acquire Media Administrator for assistance to modify the default timezone.

The returned result is a schedule ID used to retrieve the schedule details with the newsletter/getschedule API.
Request
```
https://secure.newsedge.com/opensapi/20/newsletter/addschedule?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&days=1,4&type=periodic&startTime=080000&endTime=170000&periodInSeconds=1800
```
Response
```
<opens-api>
  <status>OK</status>
  <scheduleID>402</scheduleID>
  </opens-api>
```

Review the newsletter is set with the new schedule.

Request

https://secure.newsedge.com/opensapi/20/newsletter/info?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104

Response

<opens-api>
  <status>OK</status>
  <newsletter id="2104" name="Industry Update" desc="" enableAutoPublish="FALSE" enableHighlighting="TRUE" tocFormat="SECTION" storyFormat="HEADLINE" level="USER" permission="WRITE"><topArt id="868" name="Globe with dotted overlay" link="https://secure.newsedge.com/art/32966_USER_20190129091338004.jpg"/>
    <title>Pharmaceutical Industry Update</title>
    <dateFormat location="FOLLOW"><%B> <%e>, <%Y></dateFormat>
    <includePagetop>TRUE</includePagetop>
    <dateSubject>TRUE</dateSubject>
    <introduction><p>In the newsletter today are some top stories about our competitors and their new products at this year's annual trade show. </p><p>If you have any news to share with the rest of the company, please forward your items to Jane Doe, <a href="mailto:jdoe@mycompany.com?subject=Pharmaceutical%20News%20Update">jdoe@mycompany.com</a>.</p></introduction>
    <tocComment/>
    <lastExecTime>20190520T160927-0400</lastExecTime>
    <sections count="3"><section id="3456"/>
      <section id="3467"/>
      <section id="3455"/>
    </sections>
    <schedules count="1">
      <schedule id="402"/>
    </schedules>
    <bottomArt id="876" name="NewsEdge light" link="https://secure.newsedge.com/art/32966_USER_20190520134258415.png"/>
    <footer/>
  </newsletter>
</opens-api>

Get the schedule.

With the schedule ID, request the newsletter/getschedule results to confirm the set up is for delivery on Mondays and Thursdays, every 30 minutes beginning at 8AM throughout the day until 5PM.

Request

https://secure.newsedge.com/opensapi/20/newsletter/getschedule?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&schedule=402

Response

<opens-api>
  <status>OK</status>
  <schedule id="402 ">
    <dayOfWeek number="1,4">
      <startTime>T080000-0500</startTime>
      <endTime>T170000-0500</endTime>
      <period>PT30M</period>
    </dayOfWeek>
  </schedule>
</opens-api>

Activate the newsletter to publish every 30 minutes.

Use the newsletter/update API and the parameter enableAutoPublish with value TRUE.

Request

https://secure.newsedge.com/opensapi/20/newsletter/update?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2104&enableAutoPublish=TRUE

Response

<opens-api>
  <status>OK</status>
</opens-api>

Managing Newsletters

List newsletters.

To review the newsletters owned or shared with your OPENS API account use the newsletter/list API. From the returned results, the newsletter ID can be used with the other newsletter APIs to update and manage a particular newsletter, e.g. use the newsletter/info API to retrieve more details about the selected newsletter.

Note: the OPENS API user is a member of a NewsEdge group and may have access to newsletters shared between members of your group. The newsletter attribute level is either USER or GROUP. In the sample returned results, the newsletter with ID=2106 and named Market Update for Sales Group, is a group-level newsletter that is viewable and can be published by the OPENS API user. However, modifying the group-shared newsletter is dependent on the OPENS API privileges. Contact the Acquire Media Administrator with questions about rights to manage and modify shared newsletters.

Request

https://secure.newsedge.com/opensapi/20/newsletter/list?session=935DA0B364E9E130F0EC3827FC3CCC9C

Response

<opens-api>
  <status>OK</status>
  <newsletters type="ALL">
    <newsletter id="2106" name="Market Update for Sales Group" owner="API Group" level="GROUP" permission="READ" schedule="NONE" enableAutoPublish="FALSE" enableHighlighting="" desc="" createdBy="API User" modifiedBy="Publishing Manager" modifiedOn="20190114T153416-0500"/>
    <newsletter id="2104" name="Industry Update" owner="OPENS API Trial User" level="USER" permission="WRITE" schedule="ACTIVE" enableAutoPublish="FALSE" enableHighlighting="TRUE" desc="" createdBy="API User" modifiedBy="API User" modifiedOn="20190521T135656-0400"/>
    <newsletter id="2115" name="Newsletter for Sales" owner="OPENS API Trial User" level="USER" permission="WRITE" schedule="ACTIVE" enableAutoPublish="FALSE" enableHighlighting="TRUE" desc="" createdBy="API User" modifiedBy="API User" modifiedOn="20190213T131136-0500"/>
  </newsletters>
</opens-api>

Delete a newsletter.
Successfully delete a newsletter owned by the OPENS API user using the newsletter/delete API and the ID with the newsletter parameter. In this example, newsletter with ID 2115 will be deleted.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/delete?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2115
```
Response
```
<opens-api>
  <status>OK</status>
</opens-api>
```
Delete a newsletter without proper rights.
In this example, use the newsletter/delete API to delete the group level newsletter with ID 2106. An error is returned when the OPENS API user does not have the rights to delete a shared template.

Request
```
https://secure.newsedge.com/opensapi/20/newsletter/delete?session=935DA0B364E9E130F0EC3827FC3CCC9C&newsletter=2106
```
Response
```
<opens-api>
  <status>ERROR</status>
  <error>INVALID PUBLISHER LEVEL</error>
</opens-api>
```

newsletter/create - Build a newsletter

Use the newsletter/create API to add a new newsletter. Additional Publishing APIs are available to configure the newsletter. See also api/info where noun=newsletter and verb=create.

Example

https://secure.newsedge.com/opensapi/20/newsletter/create?session=<<user-token>>&name=<<newsletter-name>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
name	url encoded string of length 50 or less	The name for this newsletter.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.
title	url encoded string of length 50 or less	The newsletter title appearing at the top of the newsletter. This text is also presented as the email subject line.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
dateFormat	Default:<%Y><%m><%d>	Defines how the date is presented at the top of the newsletter. Define the date format by using the following elements along with any necessary punctuation, e.g. forward slash (/), pipe-delimiter (\|), hyphen (-), or comma (,). <%a> - Day of the week written in short form, e.g. Mon, Tue, Wed, etc. <%A> - Day of the week written in long form, e.g. Monday, Tuesday, Wednesday, etc. <%_m> - Month expressed in single digit numeric form, e.g. 1 for January, 2 for February, ..., through to 12 for December. <%m> - Month expressed in double digit numeric form, e.g. 01 for January, 02 for February, ..., through to 12 for December. <%b> - Month written in short form, e.g. Jan, Feb, Mar, etc. <%B> - Month written in long form, e.g. January, February, March, etc. <%e> - Day of month expressed in single digit numeric form, e.g. 1, 2, 3, ..., 30, 31. <%d> - Day of month expressed in double digits numeric form, e.g. 01, 02, 03, ..., 30, 31. <%ord> - Include ordinal after the day of month, e.g. st after the 1st, nd after the 2nd, etc. <%y> - Year in double digit numeric form, e.g. 18 for 2018, 19 for 2019, etc. <%Y> - Year in four digit numeric form, e.g. 2018, 2019, etc.
dateLocation	Default:APPEND APPEND, FOLLOW	Determines the placement of the newsletter date. APPEND - Show the date on the same line as the newsletter title. FOLLOW - Show the date on the line following the newsletter title.
dateSubject	Default:TRUE TRUE, FALSE	Determines if the date will be included in the newsletter's email subject line. TRUE - Include the date in the email subject, following the newsletter title text. FALSE - Do not include the date in the email subject.
description	url encoded string of length 200 or less	A description of the newsletter.
enableAutoPublish	Default:FALSE TRUE, FALSE	Determines if the newsletter is to be sent automatically based on a defined schedule. TRUE - the newsletter will be automatically sent using the defined schedule. The schedule parameter is required. FALSE - the newsletter is not automatically sent. To publish the newsletter, use the newsletter/send API.
enableHighlighting	Default:TRUE TRUE, FALSE	Determines whether search terms will be highlighted for newsletter stories. Note: highlighting is only available when the section dataSourceType is Search. true - highlight terms matching the search query. false - do not highlight terms.
footer	url encoded string of length 2,500 or less	Include footer text at the end of the newsletter, after the last story and before the art at the end of the newsletter. The footer text can include HTML markup.
includePagetop	Default:FALSE TRUE, FALSE	Determines if a link to return to the Table of Contents will be inserted for each newsletter item. Not applicable if tocFormat is set to NONE.
introduction	url encoded string of length 2,500 or less	Include introductory text at the beginning of the newsletter, after the newsletter title and date, and before the table of contents and newsletter sections. The introduction text can include HTML markup.
storyFormat	Default:BRIEF HEADLINE, BRIEF, FULL	Set the story format used for each item in newsletter sections. HEADLINE - show story headline only. BRIEF - show the story headline and a story summary. FULL - show the story headline and full text of the story. Note: full text is displayed for Licensed content only.
tocComment	url encoded string of length 2,500 or less	Text to show above the table of contents. The tocComment is not displayed when the tocFormat is set to NONE. The table of contents text can include HTML markup.
tocFormat	Default:HEADLINE NONE, SECTION, HEADLINE, BRIEF	Determines the format of the table of contents. NONE - do not include a table of contents. SECTION - include a table of contents with only the section names. HEADLINE - include a table of contents with section names and headlines within each section. BRIEF - include a table of contents with section names, headlines and story summaries.

Returned Results

The returned results from newsletter/create include an opens-api element that contains status and newsletter child elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.
newsletter		The numerical identifier for the newly created newsletter.

newsletter/list - List newsletters

Use newsletter/list api to display a list of newsletter templates sorted alphabetically by name. Each newsletter will have an id attribute representing the newsletter template ID, along with additional attributes. Use this ID value with newsletter/info to see specific configuration details. See also api/info where noun=newsletter and verb=list and newsletter/info.

Example

https://secure.newsedge.com/opensapi/20/newsletter/list?session=<<user-token>>[&parameter=value]

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/list include an opens-api element that contains status child element and newsletters child element representing a list of newsletters. The newsletters element holds one or more newsletter child elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.
newsletters		The newsletters element represents the list of newsletters where each newsletter is represented by a newsletter child element. The newsletters element includes a type attribute with value ALL, meaning the list includes all newsletters available to the API user.

newsletters

The newsletters element contains zero or more newsletter child elements.

Name	Values	Description
newsletter		The newsletter element represents a newsletter template and has the following attributes: id - The numerical identifier representing the newsletter, for use with other API requests. name - The newsletter template name. owner - The owner of the newsletter. For USER level newsletter templates, the owner is the current user. For GROUP level templates, the owner is the group name. For account level templates, the owner is the account name. level - The level of the newsletter is calculated by OPENS and indicates who owns the newsletter template. Valid values are USER (current user), GROUP (current user and others in the same group), ACCOUNT (current user and others in the same organization). The default value is USER. permission - The newsletter permission settings for the current user. The valid values for permission are: READ means you can view details of the newsletter but cannot make changes. WRITE means you can define and modify the newsletter settings. schedule - A calculated value indicating whether the newsletter is scheduled or not. Valid values are NONE or ACTIVE. Use newsletter/addschedule to configure the schedule, newsletter/getschedule to review the schedule or newsletter/deleteschedule to remove the schedule. Successfully adding a schedule will result in an ACTIVE value for this attribute. enableAutoPublish - Indicates if the newsletter is set to automatically send the newsletter based on the defined schedule. Valid values are: TRUE meaning the newsletter is set to publish automatically, and FALSE which means the newsletter does not publish automatically. Before setting the value to TRUE, the schedule must have value ACTIVE. enableHighlighting - Indicates if the search results will include highlighted search terms. desc - A description for this newsletter. createdBy - The newsletter creator. modifiedBy - The last user to modify the newsletter template. modifiedOn - The date and time the newsletter template was last modified.

Name

Values

Description

newsletter

The newsletter element represents a newsletter template and has the following attributes:

id - The numerical identifier representing the newsletter, for use with other API requests.

name - The newsletter template name.

owner - The owner of the newsletter. For USER level newsletter templates, the owner is the current user. For GROUP level templates, the owner is the group name. For account level templates, the owner is the account name.

level - The level of the newsletter is calculated by OPENS and indicates who owns the newsletter template. Valid values are USER (current user), GROUP (current user and others in the same group), ACCOUNT (current user and others in the same organization). The default value is USER.

permission - The newsletter permission settings for the current user. The valid values for permission are: READ means you can view details of the newsletter but cannot make changes. WRITE means you can define and modify the newsletter settings.

schedule - A calculated value indicating whether the newsletter is scheduled or not. Valid values are NONE or ACTIVE. Use newsletter/addschedule to configure the schedule, newsletter/getschedule to review the schedule or newsletter/deleteschedule to remove the schedule. Successfully adding a schedule will result in an ACTIVE value for this attribute.

enableAutoPublish - Indicates if the newsletter is set to automatically send the newsletter based on the defined schedule. Valid values are: TRUE meaning the newsletter is set to publish automatically, and FALSE which means the newsletter does not publish automatically. Before setting the value to TRUE, the schedule must have value ACTIVE.

enableHighlighting - Indicates if the search results will include highlighted search terms.

desc - A description for this newsletter.

createdBy - The newsletter creator.

modifiedBy - The last user to modify the newsletter template.

modifiedOn - The date and time the newsletter template was last modified.

newsletter/info - Get newsletter details

Use newsletter/info api to get details and configuration settings of a newsletter. See also api/info where noun=newsletter and verb=info and newsletter/list API.

Example

https://secure.newsedge.com/opensapi/20/newsletter/info?session=<<user-token>>&newsletter=<<newsletter-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/info include an opens-api element that contains status and a newsletter child element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.
newsletter		The newsletter element describes the newsletter template details with child elements to further describe its configuration. Newsletter attributes include: id - The unique identifier for a newsletter. name - The newsletter template name. desc - The newsletter template description. enableAutoPublish - Indicates if the newsletter is set to automatically send the newsletter based on the defined schedule. Valid values are: TRUE meaning the newsletter is set to publish automatically, and FALSE which means the newsletter does not publish automatically. enableHighlighting - Indicates if the search results will include highlighted search terms. tocFormat - Indicates if the newsletter will include a Table of Contents. Allowed values are: NONE, SECTION, HEADLINE, and BRIEF. See newsletter/create optional parameter tocFormat for more details. storyFormat - Indicates the story format applied to items in the newsletter. Allowed values are: HEADLINE, BRIEF, and STORY. See newsletter/create optional parameter storyFormat for more details. level - The level of the newsletter is calculated by OPENS and indicates who owns the newsletter template. Valid values are USER (current user), GROUP (current user and others in the same group), ACCOUNT (current user and others in the same organization). The default value is USER. permission - The newsletter permission settings for the current user. The valid values for permission are: READ means you can view details of the newsletter. WRITE means you can define and modify the newsletter settings.
topArt		The topArt element indicates the image to insert at the beginning of the newsletter. It includes the following attributes: id - The image identifier. name - The name assigned to the image. link - The image link.
title		The title element is the text inserted at the top of the newsletter, after the top art image, if available. The title text is also used as the email subject line.
dateFormat		The dateFormat element describes the way the newsletter date is presented and its location attribute indicates where the newsletter date is inserted. The date format is a formula written with the following codes, along with any necessary punctuation, e.g. forward slash (/), pipe-delimiter (\|), hyphen (-), or comma (,). <%a> - Day of the week written in short form, e.g. Mon, Tue, Wed, etc. <%A> - Day of the week written in long form, e.g. Monday, Tuesday, Wednesday, etc. <%_m> - Month expressed in single digit numeric form, e.g. 1 for January, 2 for February, ..., through to 12 for December. <m> - Month expressed in double digit numeric form, e.g. 01 for January, 02 for February, ..., through to 12 for December. <%b> - Month written in short form, e.g. Jan, Feb, Mar, etc. <%B> - Month written in long form, e.g. January, February, March, etc. <%e> - Day of month expressed in single digit numeric form, e.g. 1, 2, 3, ..., 30, 31. <%d> - Day of month expressed in double digits numeric form, e.g. 01, 02, 03, ..., 30, 31. <%ord> - Include ordinal after the day of month, e.g. st after the 1st, nd after the 2nd, etc. <%y> - Year in double digit numeric form, e.g. 18 for 2018, 19 for 2019, etc. <%Y> - Year in four digit numeric form, e.g. 2018, 2019, etc. The location attribute has two valid values: APPEND - Display date on same line as the title. FOLLOW - Display date on line after title.
includePagetop	TRUE, FALSE	Describes whether there will be a link to return to the Table of Contents for each newsletter item. TRUE - Do show page top link. FALSE - Do not show page top link.
dateSubject	TRUE, FALSE	Describes whether the date is included in the newsletter's email subject line. TRUE - include the date in the email subject, following the newsletter title text. FALSE - do not include the date in the email subject.
introduction		Include introductory text at the beginning of the newsletter, after the newsletter title and date, and before the table of contents and newsletter sections.
tocComment		Text to show above the table of contents. The comment does not appear when the tocFormat is set to none.
lastExecTime	YYYYMMDDTHHMMSS-ZZZZ	The last date and time the newsletter was published.
sections		The sections element represents the newsletter categories, with the count attribute indicating the number of categories. If the count is higher than one, then one or more additional section sub-elements are listed. The section sub-element has the id attribute representing the unique section identifier. Use the newsletter/getsection to see the section details.
schedules		The schedules element attribute count indicates if there is zero, one or more schedules associated to the newsletter. If the count is zero, the newsletter is not scheduled and will not be published automatically by OPENS. Where the count is one or higher, the schedule sub-element identifies the schedule ID.
schedule		The schedule element is available when a schedule is defined using the newsletter/addschedule API. The id attribute is a unique identifier used with the newsletter/getschedule to retrieve the appointed day(s) of week and time(s) of day when the newsletter will be automatically published. If
bottomArt		The bottomArt element indicates the image to insert at the end of the newsletter, following the footer text, if available. It includes the following attributes: id - The image identifier. name - The name assigned to the image. link - The image link.
footer		The text to display at the end of the newsletter, after the last story and before the art at the end of the newsletter.

newsletter/update - Update a newsletter

Use the newsletter/update API to modify and configure the newsletter. Additional Publishing APIs are available to configure the newsletter. See also api/info where noun=newsletter and verb=update.

Example

https://secure.newsedge.com/opensapi/20/newsletter/update?session=<<user-token>>&newsletter=<<newsletter-id>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
newsletter		The identifier for this newsletter. The identifier is obtained from the value of the newsletter element resulting from the newsletter/list or the newsletter/create request.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
dateFormat	Default:<%Y><%m><%d>	Defines how the date is presented at the top of the newsletter. Define the date format by using the following elements along with any necessary punctuation, e.g. forward slash (/), pipe-delimiter (\|), hyphen (-), or comma (,). <%a> - Day of the week written in short form, e.g. Mon, Tue, Wed, etc. <%A> - Day of the week written in long form, e.g. Monday, Tuesday, Wednesday, etc. <%_m> - Month expressed in single digit numeric form, e.g. 1 for January, 2 for February, ..., through to 12 for December. <%m> - Month expressed in double digit numeric form, e.g. 01 for January, 02 for February, ..., through to 12 for December. <%b> - Month written in short form, e.g. Jan, Feb, Mar, etc. <%B> - Month written in long form, e.g. January, February, March, etc. <%e> - Day of month expressed in single digit numeric form, e.g. 1, 2, 3, ..., 30, 31. <%d> - Day of month expressed in double digits numeric form, e.g. 01, 02, 03, ..., 30, 31. <%ord> - Include ordinal after the day of month, e.g. st after the 1st, nd after the 2nd, etc. <%y> - Year in double digit numeric form, e.g. 18 for 2018, 19 for 2019, etc. <%Y> - Year in four digit numeric form, e.g. 2018, 2019, etc.
dateLocation	Default:APPEND APPEND, FOLLOW	Determines the placement of the newsletter date. APPEND - Show the date on the same line as the newsletter title. FOLLOW - Show the date on the line following the newsletter title.
dateSubject	Default:TRUE TRUE, FALSE	Determines if the date will be included in the newsletter's email subject line. TRUE - Include the date in the email subject, following the newsletter title text. FALSE - Do not include the date in the email subject.
description	url encoded string of length 200 or less	A description of the newsletter.
enableAutoPublish	Default:FALSE TRUE, FALSE	Determines if the newsletter is to be sent automatically based on a defined schedule. TRUE - the newsletter will be automatically sent using the defined schedule. See the newsletter/addschedule API to set up the schedule. FALSE - the newsletter is not automatically sent. To publish the newsletter, use the newsletter/send API.
enableHighlighting	Default:TRUE TRUE, FALSE	Determines whether search terms will be highlighted for newsletter stories. Note: highlighting is only available when the section dataSourceType is Search. true - highlight terms matching the search query. false - do not highlight terms.
footer	url encoded string of length 2,500 or less	Include footer text at the end of the newsletter, after the last story and before the art at the end of the newsletter. The footer text can include HTML markup.
includePagetop	Default:FALSE TRUE, FALSE	Determines if a link to return to the Table of Contents will be inserted for each newsletter item. Not applicable if tocFormat is set to NONE.
introduction	url encoded string of length 2,500 or less	Include introductory text at the beginning of the newsletter, after the newsletter title and date, and before the table of contents and newsletter sections. The introduction text can include HTML markup.
name	url encoded string of length 50 or less	The name for this newsletter.
storyFormat	Default:BRIEF HEADLINE, BRIEF, FULL	Set the story format used for each item in newsletter sections. HEADLINE - show story headline only. BRIEF - show the story headline and a story summary. FULL - show the story headline and full text of the story. Note: full text is displayed for Licensed content only.
title	url encoded string of length 50 or less	The newsletter title appearing at the top of the newsletter. This text is also presented as the email subject line.
tocComment	url encoded string of length 2,500 or less	Text to show above the table of contents. The tocComment is not displayed when the tocFormat is set to NONE. The table of contents text can include HTML markup.
tocFormat	Default:HEADLINE NONE, SECTION, HEADLINE, BRIEF	Determines the format of the table of contents. NONE - do not include a table of contents. SECTION - include a table of contents with only the section names. HEADLINE - include a table of contents with section names and headlines within each section. BRIEF - include a table of contents with section names, headlines and story summaries.

Returned Results

The returned results from newsletter/update include an opens-api element that contains status and newsletter child elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.
newsletter		The numerical identifier for the newly created newsletter.

newsletter/addsection - Add a section to the newsletter

Use newsletter/addsection to add a newsletter section displaying stories (from a saved search or a story folder) or displaying other content marked up as HTML. Then use the newsletter/updatesection to configure the specifics for the section and newsletter/getsection to review the details for the section. A newsletter may have one or more sections. See also api/info where noun=newsletter and verb=addsection.

Example

https://secure.newsedge.com/opensapi/20/newsletter/addsection?session=<<user-token>>&newsletter=<<newsletter-id>>&name=<<section-name>>&dataSourceType=SEARCH&search=<<search-id>>[&parameter=value][& . . .]

https://secure.newsedge.com/opensapi/20/newsletter/addsection?session=<<user-token>>&newsletter=<<newsletter-id>>&name=<<section-name>>&dataSourceType=FOLDER&folder=<<folder-id>>[&parameter=value][& . . .]

https://secure.newsedge.com/opensapi/20/newsletter/addsection?session=<<user-token>>&newsletter=<<newsletter-id>>&name=<<section-name>>&dataSourceType=HTML[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
dataSourceType	FOLDER, SEARCH, HTML	The dataSourceType represents the type of content used to populate the newsletter section. The allowed values are: FOLDER - use the contents of a story folder to populate the newsletter section. When the data type is FOLDER, the folder parameter is required. SEARCH - use the results of a search to populate the newsletter section. When data type is SEARCH, the search parameter is required. HTML - use HTML mark-up to add content to the section. An HTML based section can be left empty, or use the optional parameter html to define the HTML mark-up.
name	url encoded string of length 50 or less	The name for the newsletter section.
newsletter		The newsletter identifier. Use the value of the newsletter element from the newsletter/list request.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
comment	url encoded string of length 2,500 or less	A comment describing the section for the newsletter reader. This text is displayed in the newsletter beneath the section name and can be formatted using HTML markup.
emptySectionMessage	url encoded string of length 50 or less	Define the message text to display when a section contains no results. This is required when the optional parameter includeEmptySection is set to TRUE.
folder		The story folder identifier. A number of stories from the folder, where the story status as "ACTIVE", will be used to populate this section. The number of stories is set by the value of the storyLimit parameter. This parameter is required when dataSourceType value is FOLDER.
html	url encoded string	When the dataSourceType is HTML, use html parameter to define the content for this section.
includeEmptySection	Default:FALSE TRUE, FALSE	Sets whether the section appears in the newsletter if there are no stories to be displayed. TRUE - show the section heading even when no stories are found. When this value is true, the parameter emptySectionMessage is required and its text is displayed beneath the section heading text. FALSE - do not show the section heading when no stories are found in the linked story folder or saved search.
search		The saved search identifier. A number of results from the search will be used to populate this section. The number of stories is set by the value of the storyLimit parameter. This parameter is required when dataSourceType value is SEARCH.
storeOnSend	TRUE, FALSE	Indicates if the stories in the folder will be changed from ACTIVE to STORED once the newsletter is sent. See also status parameter for storyfolder/updatestory.
storyLimit	Default:10 1,2,3,...100	The number of stories to display in the section.

Returned Results

The returned results from newsletter/addsection include an opens-api element that contains status and sectionID sub-elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.
sectionID		The numeric identifier for the section to be used with other API requests.

newsletter/getsection - Retrieve the newsletter section configurations

Use newsletter/getsection to retrieve the details of a newsletter section created or updated with the newsletter/addsection or newsletter/updatesection APIs, respectively. See also newsletter/addsection, newsletter/updatesection, and api/info where noun=newsletter and verb=getsection.

Example

https://secure.newsedge.com/opensapi/20/newsletter/getsection?session=<<user-token>>&newsletter=<<newsletter-id>>&section=<<section-id>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
newsletter		The newsletter identifier. Use the value of the newsletter element from the newsletter/list request.
section		The section identifier. Use the value of the sectionID element from the newsletter/addsection or newsletter/info request.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/getsection include an opens-api element that contains status and section sub-elements.

opens-api

Name

Values

Description

status

OK, ERROR

The status of the request.

OK - Request completed successfully.
ERROR - An error occurred with the request. An error element contains a description of the error.

section

Represents a newsletter category and includes the following attributes:

id - The numeric identifier for the section to be used with other API requests.

order - The numeric position of the section as it appears in the newsletter. A value of 1 means this is the first section in the newsletter. The higher the number the further down it appears in the newsletter.

name - The section name.

storyLimit - The number of articles to display in this section.

dataSourceType - The type of content displayed in this section.

storyfolder - The story folder identifier.

savedsearch - The saved search identifier.

sectionHtml - The HTML markup to show in the section.

comment - Text to display as a comment for this section.

dataSourceName - The name of the story folder or saved search linked to the section.

sendEmptySection - Indicates if the section will be included in the newsletter even when there are no stories to display.

emptySectionMessage - When sendEmptySection is TRUE, this text is displayed in the section.

storeOnSend - When dataSourceType is FOLDER, this element indicates if the stories in the folder will be changed from ACTIVE to STORED once the newsletter is sent.

newsletter/updatesection - Configure and modify a newsletter section

Use newsletter/updatesection to define different elements of the section, such as what content to display, how many results to display, whether to include an introductory comment for this section, set the position of section within the newsletter, etc. Use the newsletter/getsection request to review and confirm your section changes. See also api/info where noun=newsletter and verb=updatesection.

Example

https://secure.newsedge.com/opensapi/20/newsletter/updatesection?session=<<user-token>>&newsletter=<<newsletter-id>>&section=<<section-id>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
newsletter		The newsletter identifier. Use the value of the newsletter element from the newsletter/list request.
section		The section identifier. Use the value of the sectionID element from the newsletter/addsection or newsletter/info request.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
comment	url encoded string of length 2,500 or less	A comment describing the section for the newsletter reader. This text is displayed in the newsletter beneath the section name and can be formatted using HTML markup.
dataSourceType	FOLDER, SEARCH, HTML	The dataSourceType represents the type of content used to populate the newsletter section. The allowed values are: FOLDER - use the contents of a story folder to populate the newsletter section. When the data type is FOLDER, the folder parameter is required. SEARCH - use the results of a search to populate the newsletter section. When data type is SEARCH, the search parameter is required. HTML - use HTML mark-up to add content to the section. An HTML based section can be left empty, or use the optional parameter html to define the HTML mark-up.
emptySectionMessage	url encoded string of length 50 or less	Define or modify the message text to display when a section contains no results. This is required when the optional parameter includeEmptySection is set to TRUE.
folder		The story folder identifier. A number of stories from the folder, where the story status as "ACTIVE", will be used to populate this section. The number of stories is set by the value of the storyLimit parameter. This parameter is required when dataSourceType value is FOLDER.
html	url encoded string	When the dataSourceType is HTML, use html parameter to define the content for this section.
includeEmptySection	Default:FALSE TRUE, FALSE	Sets whether the section appears in the newsletter if there are no stories to be displayed. TRUE - show the section heading even when no stories are found. When this value is true, the parameter emptySectionMessage is required and its text is displayed beneath the section heading text. FALSE - do not show the section heading when no stories are found in the linked story folder or saved search.
name	url encoded string of length 50 or less	The name for the newsletter section.
order	1,2,3,...	The numeric position of the section as it appears in the newsletter. A value of 1 means this is the first section in the newsletter. The higher the number the further down it appears in the newsletter.
search		The saved search identifier. A number of results from the search will be used to populate this section. The number of stories is set by the value of the storyLimit parameter. This parameter is required when dataSourceType value is SEARCH.
storeOnSend	TRUE, FALSE	Indicates if the stories in the folder will be changed from ACTIVE to STORED once the newsletter is sent. See also status parameter for storyfolder/updatestory.
storyLimit	Default:10 1,2,3,...100	The number of stories to display in the section.

Returned Results

The returned results from newsletter/updatesection include an opens-api element that contains status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/deletesection - Delete a newsletter category

Use the newsletter/deletesection to permanently remove a newsletter category. See also api/info where noun=newsletter and verb=deletesection.

Example

https://secure.newsedge.com/opensapi/20/newsletter/deletesection?session=<<user-token>>&newsletter=<<newsletter-id>>&section=<<section-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
newsletter		The newsletter identifier. Use the value of the newsletter element from the newsletter/list request.
section		The section identifier. Use the value of the sectionID element from the newsletter/addsection or newsletter/info request.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/deletesection include an opens-api element that contains status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/preview - Prepare to preview the newsletter

The newsletter/preview api generates a unique key value for the newsletter which is submitted with the newsletter/checkpreview request to obtain a URL. This URL returns the newsletter formatted with the stories as defined either by the section details or as submitted with the storyxml parameter.

See also newsletter/checkpreview and api/info where noun=newsletter and verb=preview.

Example

https://secure.newsedge.com/opensapi/20/newsletter/preview?session=<<user-token>>&newsletter=<<newsletter-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter

Values

Description

json

Default:0
0,1,2

The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format.

0 - Return data in XML format.
1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used.
2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

storyxml

The storyxml parameter is used to submit encoded XML content for display within the indicated newsletter section(s).

Note, you will want to use an HTTP Post command to submit the story due to the typical 2,000 character limit for HTTP urls. The following example show the storyXML format to send 3 stories in the newsletter section with id=5345.

Sample storyxml:

 <?xml version="1.0" encoding="UTF-8"?>
 <newsletter-stories>
 <section id="5345">
 <story>
 <storyURL>https://secure.newsedge.com/?cmmd=readstory&key=1iprmmZU5aSUiabbJv8LciJ5nhMxUtsOyrYhwCQJrPT98XZB7VxvG01Q_g2NxbU7EdWld_q4MDYQ2xRa5_wk_ONwME88tVTbAgamcqMdiEhBP5QWcHPvJJCURzWe4ArnyEUU2r8tlEAvGjS1SV_oFMiherEeE26onHtlY9qRAtE*</storyURL>
 </story>
 <story>
 <storyURL>https://secure.newsedge.com/?cmmd=readstory&key=NtcP_dRRldtTf6bKYu_p25vC6-JnzJhpCmDORAS6YVZ1n4EPPoVtR6abP6bCybyR6W7NvQP4U8WasIBP891ZWtRX1eNXdVu_oBpYn-srZhI1J83lpJAjsmmxdW91XvtGwCWNsqP5c20RQ8LkGFsNOg**</storyURL>
 </story>
 <story>
 <storyURL>https://secure.newsedge.com/?cmmd=readstory&key=UZs_rkT_clOjUC4mLq8wPJtBQUxE7mRU0iPrh--2pzEt74SXRg8d8q4OtxX-WkOgZteSM-dh128MarAIWXb32-74jBckbZKM28nmKLmDVwn0d7-qP2CShnMGO8V6QadMTdYlXItP2Bdj9O1Zm0947g**</storyURL>
 </story>
 </section>
 </newsletter-stories>

newsletter-stories - A list of sections and stories to include in the newsletter. Newsletter-stories may contain one or more section id elements.

section - Defines the section where the list of one or more stories are to appear. When the newsletter section has predefined folder, search or HTML contents, the content submitted with the storyxml parameter overrides the stories from the folder, search or HTML.

Each story element requires a storyURL. If storyURL is not provided then these other story elements are required:

publication-date - The publication-date specifies the date when the news story was officially published (which may not correspond to the actual release time). This published-date is formatted according to ISO 8601 basic standard, e.g. YYYYMMDDTHHMMSS-ZZZZ

source - The source name.

wordcount - The count of the words in the story body excluding any markup. Wordcount may be empty.

headline - The headline text for the story.

summary - The summary as a short, free-form text summary of a story.

storyType - Specifies the general type of information in the story. The code values are defined by Acquire Media as:

pub-source - for a weblinked story.
associated-media - for an image
if storyType is empty, this story is not weblinked and does not have any associated image(s).

image - Optionally, include an image with the story using the artlink URL returned by the art/upload API.

comment - Optionally, include a comment to display with newsletter story.

Returned Results

The returned results from newsletter/preview include an opens-api element that contains status and key sub-elements.

opens-api

Name	Values	Description
status	PENDING, ERROR	The status of the request. PENDING - Request is processing. ERROR - An error occurred with the request. An error element contains a description of the error.
key		Key element is an identifier for the newsletter with its story contents. The value is to be used with the newsletter/checkpreview to obtain a URL to preview the newsletter.

newsletter/checkpreview - Get the URL to preview your newsletter

Use the newsletter/checkpreview API with the key value from the newsletter/preview to obtain a URL to preview the newsletter. The preview displays the newsletter formatted in HTML and populated with stories in each section. See also newsletter/preview and api/info where noun=newsletter and verb=checkpreview.

Example

https://secure.newsedge.com/opensapi/20/newsletter/checkpreview?session=<<user-token>>&key=<<key>>[&parameter=value]

Required Parameters

Parameter	Values	Description
key		An identifier for the newsletter and its contents. Obtain the key value from the newsletter/preview API results.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/checkpreview include an opens-api element that contains status sub-element.

opens-api

Name	Values	Description
status	OK, PENDING, ERROR	The status of the request. OK - Request completed successfully. PENDING - The newsletter preview is not ready yet. Try the requesting again. ERROR - An error occurred with the request. An error element contains a description of the error.
url		A hyperlink to view the newsletter in HTML. The newsletter will be displayed with stories as defined by the section settings.

newsletter/addemail - Add a newsletter recipient

Use newsletter/addemail API to add an email address as a recipient for your newsletter. See also api/info where noun=newsletter and verb=addemail.

Example

https://secure.newsedge.com/opensapi/20/newsletter/addemail?session=<<user-token>>&newsletter=<<newsletter-id>>&emailAddress=<<email-address>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
emailAddress	url encoded string as a valid email format	The newsletter recipient's email address.
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
firstName		The recipient's first name.
lastName		The recipient's last name.

Returned Results

The returned results from newsletter/addemail include an opens-api element that contains the status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/getemaillist - Get the newsletter recipient emails

The newsletter/getemaillist API returns the list of email addresses registered to receive the newsletter. See also api/info where noun=newsletter and verb=getemaillist.

Example

https://secure.newsedge.com/opensapi/20/newsletter/getemaillist?session=<<user-token>>&newsletter=<<newsletter-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/getemaillist include an opens-api element that contains status and emailList sub-elements.

opens-api

Name

Values

Description

status

OK, ERROR

The status of the request.

OK - Request completed successfully.
ERROR - An error occurred with the request. An error element contains a description of the error.

emailList

The emailList is a list of email addresses to receive this newsletter. The emailList element includes the following attributes:

The emailList element also contains one or more email sub-elements whose attributes define the email settings.

emailList

Name	Values	Description
email		email is one newsletter recipient. Attributes of email include the following: firstName - the recipient's first name. This value is optional. lastName - the recipient's last name. This value is optional. email - the recipient's email address. status - the status of the email address. The default value is normally ACTIVE meaning the recipient is set to receive the newsletter.

Name

Values

Description

email is one newsletter recipient. Attributes of email include the following:

firstName - the recipient's first name. This value is optional.

lastName - the recipient's last name. This value is optional.

email - the recipient's email address.

status - the status of the email address. The default value is normally ACTIVE meaning the recipient is set to receive the newsletter.

newsletter/deleteemail - Delete a newsletter recipient

Use newsletter/deleteemail to permanently remove an email address from the newsletter distribution. See also api/info where noun=newsletter and verb=deleteemail.

Example

https://secure.newsedge.com/opensapi/20/newsletter/deleteemail?session=<<user-token>>&newsletter=<<newsletter-id>>&emailAddress=<<email-address>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
emailAddress	url encoded string as a valid email format	The newsletter recipient's email address.
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/deleteemail include an opens-api element that contains status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/send - Send a newsletter

Use the newsletter/send API to assemble the newsletter elements (artwork, title, date, formatting, sections, stories, footer etc.) and to publish the entire newsletter to the associated email addresses. The returned result is a key element which may be used with newsletter/checksend to confirm if the newsletter has been sent. If the status of the newsletter/checksend is PENDING, and you wish to cancel this action, use the newsletter/cancelsend API. See also newsletter/checksend and newsletter/cancelsend APIs and api/info where noun=newsletter and verb=send.

Example

https://secure.newsedge.com/opensapi/20/newsletter/send?session=<<user-token>>&newsletter=<<newsletter-id>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter

Values

Description

json

Default:0
0,1,2

The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format.

0 - Return data in XML format.
1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used.
2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

storyxml

The storyxml parameter is used to submit encoded XML content for display within the indicated newsletter section(s).

Note, you will want to use an HTTP Post command to submit the story due to the typical 2,000 character limit for HTTP urls. The following example show the story XML format to send 3 stories in the newsletter section with id=5345.

Sample storyxml:

 <?xml version="1.0" encoding="UTF-8"?>
 <newsletter-stories>
 <section id="5345">
 <story>
 <storyURL>https://secure.newsedge.com/?cmmd=readstory&key=1iprmmZU5aSUiabbJv8LciJ5nhMxUtsOyrYhwCQJrPT98XZB7VxvG01Q_g2NxbU7EdWld_q4MDYQ2xRa5_wk_ONwME88tVTbAgamcqMdiEhBP5QWcHPvJJCURzWe4ArnyEUU2r8tlEAvGjS1SV_oFMiherEeE26onHtlY9qRAtE*</storyURL>
 </story>
 <story>
 <storyURL>https://secure.newsedge.com/?cmmd=readstory&key=NtcP_dRRldtTf6bKYu_p25vC6-JnzJhpCmDORAS6YVZ1n4EPPoVtR6abP6bCybyR6W7NvQP4U8WasIBP891ZWtRX1eNXdVu_oBpYn-srZhI1J83lpJAjsmmxdW91XvtGwCWNsqP5c20RQ8LkGFsNOg**</storyURL>
 </story>
 <story>
 <storyURL>https://secure.newsedge.com/?cmmd=readstory&key=UZs_rkT_clOjUC4mLq8wPJtBQUxE7mRU0iPrh--2pzEt74SXRg8d8q4OtxX-WkOgZteSM-dh128MarAIWXb32-74jBckbZKM28nmKLmDVwn0d7-qP2CShnMGO8V6QadMTdYlXItP2Bdj9O1Zm0947g**</storyURL>
 </story>
 </section>
 </newsletter-stories>

newsletter-stories - A list of sections and stories to include in the newsletter. Newsletter-stories may contain one or more section id elements.

Each story element requires a storyURL. If storyURL is not provided then these other story elements are required:

source - The source name.

wordcount - The count of the words in the story body excluding any markup. Wordcount may be empty.

headline - The headline text for the story.

summary - The summary as a short, free-form text summary of a story.

storyType - Specifies the general type of information in the story. The code values are defined by Acquire Media as:

pub-source - for a weblinked story.
associated-media - for an image
if storyType is empty, this story is not weblinked and does not have any associated image(s).

image - Optionally, include an image with the story using the artlink URL returned by the art/upload API.

comment - Optionally, include a comment to display with newsletter story.

Returned Results

The returned results from newsletter/send include an opens-api element that contains status and key sub-elements.

opens-api

Name	Values	Description
status	PENDING, ERROR	The status of the request. PENDING - Request is processing. ERROR - An error occurred with the request. An error element contains a description of the error.
key		Key element is an identifier for the assembled newsletter. The value is to be used with the newsletter/checksend to confirm if the newsletter has been published.

newsletter/checksend - Checks if a newsletter was sent

Use the newsletter/checksend with the key value from the newsletter/send returned results to confirm if the newsletter was published. If the response of this newsletter/checksend is PENDING, and you wish to cancel this action, use the newsletter/cancelsend with the key parameter and the same key value. See also newsletter/send and newsletter/cancelsend APIs, and the api/info where noun=newsletter and verb=checksend.

Example

https://secure.newsedge.com/opensapi/20/newsletter/checksend?session=<<user-token>>&key=<<key>>[&parameter=value]

Required Parameters

Parameter	Values	Description
key		An identifier for the newsletter and its contents. Obtain the key value from the newsletter/send API results.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/checksend include an opens-api element that contains status and email-status sub-elements.

opens-api

Name	Values	Description
status	OK, PENDING, ERROR	The status of the request. OK - Request completed successfully. PENDING - Request is processing. ERROR - An error occurred with the request. An error element contains a description of the error.
email-status	OK, PENDING, ERROR	The status of the request. OK - Request completed successfully. PENDING - Request is processing. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/cancelsend - Cancel newsletter send request

See also newsletter/send and api/info where noun=newsletter and verb=cancelsend.

Example

https://secure.newsedge.com/opensapi/20/newsletter/cancelsend?session=<<user-token>>&key=<<key>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/cancelsend include an opens-api element that contains status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

art/upload - Upload an image

Use the art/upload API to upload images for use with your newsletters. After uploading an image, use the newsletter/addtopart API to define the image as the newsletter masthead/banner or use the newsletter/addbottomart API to set the image at the end of the newsletter. Note you will want to use an HTTP Post method with the art/upload API. Supported image formats are .png, .jpg, .gif, and .bmp.

Before uploading the image, plan how you want it to appear in your newsletter and create the artwork dimensions accordingly. The API will not re-size the image.

See also api/info where noun=art and verb=upload.

Example

https://secure.newsedge.com/opensapi/20/art/upload?session=<<user-token>>&name=<<image-name>>[&parameter=value][& . . .]

Required Parameters

Parameter	Values	Description
name	url encoded string of length 50 or less	The name for the graphic image.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
description		An optional description for the graphic image.

Returned Results

The returned results from art/upload include an opens-api element that contains status and related art child elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.
artId		The unique identifier value for the uploaded image. The value of this element will be used in subsequent newsletter/addtopart and newsletter/addbottomart requests.
artLink		The URL to access the uploaded image hosted by OPENS.

art/list - List images

Use the art/list API to retrieve a list of the uploaded images available for use as artwork at the top or the end of the newsletter. See also art/upload and api/info where noun=art and verb=list.

Example

https://secure.newsedge.com/opensapi/20/art/list?session=<<user-token>>[&parameter=value]

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from art/list include an opens-api element that contains status and artlist child elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.
artlist		A list of the uploaded images.

artlist

Name

Values

Description

art

The art element is an image available for use with newsletters. This element has the following attributes:

id - The numerical identifier representing the image, for use with other newsletter and art API requests.

name - The name given to the image.

level - The level of the art is calculated by OPENS and indicates who owns the image. Valid values are USER (current user), GROUP (current user and others in the same group), ACCOUNT (current user and others in the same organization). The default value is USER.

permission - The art permission settings for the current user. The valid values for permission are: READ means you can view the image only. WRITE means you can define and modify the image attributes.

link - The URL to access the uploaded image hosted by OPENS.

desc - A description for this image.

createdBy - The user who uploaded the image.

modifiedBy - The last user to modify the image.

modifiedOn - The date and time the image was last modified.

art/delete - Delete an image

Use the art/delete API to delete an uploaded image. See also api/info where noun=art and verb=delete.

Example

https://secure.newsedge.com/opensapi/20/art/delete?session=<<user-token>>&art=<<art-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.
art		The art image identifier. Use the value of the artId returned result element from the initial art/upload request or the id attribute of the art element returned by the art/list request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from art/delete include an opens-api element that contains status and art child elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/addtopart - Add image at top of the newsletter

Use newsletter/addtopart to include artwork at the top of your newsletter. Your artwork would be uploaded using the art/upload API or if already uploaded, use the art/list API to identify the image you wish to use. See also art/upload and art/list APIs and api/info where noun=newsletter and verb=addtopart.

Example

https://secure.newsedge.com/opensapi/20/newsletter/addtopart?session=<<user-token>>&newsletter=<<newsletter-id>>&art=<<art-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
art		The art image identifier. Use the value of the artId returned result element from the initial art/upload request or the id attribute of the art element returned by the art/list request.
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/addtopart include an opens-api element that contains status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/deletetopart - Delete top art from newsletter

Use newsletter/deletetopart to remove the artwork included at the top of the newsletter. Note, this request does not delete the artwork from the system; to permanently delete an image, use the art/delete API. See also api/info where noun=newsletter and verb=deletetopart.

Example

https://secure.newsedge.com/opensapi/20/newsletter/deletetopart?session=<<user-token>>&newsletter=<<newsletter-id>>&art=<<art-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
art		The art image identifier. Use the value of the artId returned result element from the initial art/upload request or the id attribute of the art element returned by the art/list request.
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/deletetopart include an opens-api element that contains status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/addbottomart - Add image at the end of the newsletter

Use newsletter/addbottomart to include artwork at the end of your newsletter. Your artwork would be uploaded using the art/upload API or if already uploaded, use the art/list API to identify the image you wish to use. See also art/upload and art/list APIs and api/info where noun=newsletter and verb=addbottomart.

Example

https://secure.newsedge.com/opensapi/20/newsletter/addbottomart?session=<<user-token>>&newsletter=<<newsletter-id>>&art=<<art-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
art		The art image identifier. Use the value of the artId returned result element from the initial art/upload request or the id attribute of the art element returned by the art/list request.
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/addbottomart include an opens-api element that contains status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/deletebottomart - Delete art from the end of your newsletter

Use newsletter/deletebottomart to remove the artwork included at the end of the newsletter. Note, this request does not delete the artwork from the system; to permanently delete an image, use the art/delete API. See also api/info where noun=newsletter and verb=deletebottomart.

Example

https://secure.newsedge.com/opensapi/20/newsletter/deletebottomart?session=<<user-token>>&newsletter=<<newsletter-id>>&art=<<art-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
art		The art image identifier. Use the value of the artId returned result element from the initial art/upload request or the id attribute of the art element returned by the art/list request.
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/deletebottomart include an opens-api element that contains status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/addschedule - Add a schedule to a newsletter

Use newsletter/addschedule to set the days and times when a newsletter is to be automatically published. See also api/info where noun=newsletter and verb=addschedule. Newsletters are scheduled for one or more days of the week using the days parameter, then the time of day can be scheduled in two ways:

To schedule a newsletter to be sent at a specific time of the day, use the type=settime with the parameter setTime.
To schedule a newsletter to be sent periodically throughout the day, use the parameter type=period with the parameters startTime, endTime and periodInSeconds.

The OPENS API user's timezone defaults to Eastern Time. Please contact the Acquire Media Administrator for assistance to modify the default timezone.

Example

https://secure.newsedge.com/opensapi/20/newsletter/addschedule?session=<<user-token>>&newsletter=<<newsletter-id>>&days=<<day-list>>&type=settime&setTime=<<hhmmss>>[&parameter=value][&...]

https://secure.newsedge.com/opensapi/20/newsletter/addschedule?session=<<user-token>>&newsletter=<<newsletter-id>>&days=<<day-list>>&type=period&startTime=<<hhmmss>>&endTime=<<hhmmss>>&periodInSeconds=<<seconds>>[&parameter=value][&...]

Required Parameters

Parameter	Values	Description
days	1,2,3,4,5,6,7 Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday all weekdays	Specifies the days of the week to send the newsletter, where each number represents a different day. Specify more than one day by separating the numbers with commas. 1 - Monday 2 - Tuesday 3 - Wednesday 4 - Thursday 5 - Friday 6 - Saturday 7 - Sunday For example: 1,3,5 specifies a newsletter is to be published on Monday, Wednesday and Friday. For Monday through Friday, set value as weekdays. For seven days per week, set value as all.
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.
type	period, settime	The type of schedule used to send the newsletter. period - The newsletter will be sent periodically, for example, hourly. This setting requires values for the following parameters: startTime endTime periodInSeconds settime - The newsletter will be sent at a specific time of day, for example, 9 AM. This setting requires a value for the setTime parameter.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.
endTime	hhmmss	Required only if parameter type=period. Sets the time when periodic newsletters end for the day. For example, if endTime=170000, no newsletters would be sent past 5:00:00 PM. The first newsletter for the day begins at the time set by the startTime parameter. Newsletter are then published periodically based on the value of the periodInSeconds parameter until the time set in the endTime parameter occurs.
periodInSeconds	900, . . .	Required only if parameter type=period. Sets the amount of time in seconds between periodic newsletters. Lowest value is 900. For example, if periodInSeconds=900 and startTime=080000, then the newsletter would first be sent at 8:00:00 AM and every 15 minutes (900 seconds) thereafter until the endTime occurs.
setTime	hhmmss	Required only if parameter type=settime. Sets a specific time of day for a newsletter to be published. For example, if setTime=164500, then the newsletter is sent at 4:45:00 PM.
startTime	hhmmss	Required only if parameter type=period. Sets the time when periodic newsletters start for the day. The first periodic newsletter is sent at the startTime. Thereafter, newsletters are sent periodically based on the value of the periodInSeconds parameter until the time set in the endTime parameter occurs.

Returned Results

The returned results include an opens-api element with a status and scheduleID sub-elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.
scheduleID		The numeric identifier for the newsletter schedule.

newsletter/getschedule - Get newsletter schedule details

Use newsletter/getschedule to retrieve the newsletter schedule. See also api/info where noun=newsletter and verb=getschedule.

The OPENS API user's timezone defaults to Eastern Time. Please contact the Acquire Media Administrator for assistance to modify the default timezone.

Example

https://secure.newsedge.com/opensapi/20/newsletter/getschedule?session=<<user-token>>&newsletter=<<newsletter-id>>&schedule=<<schedule-id>>[&parameter=value][&...]

Required Parameters

Parameter	Values	Description
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
schedule		The scheduleID value returned from the newsletter/addschedule API or the schedule ID attribute value returned by the newsletter/info API.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a status and schedule sub-elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.
schedule		The schedule element represents one newsletter schedule. The schedule id attribute is a unique identifier created by the newsletter/addschedule API. Schedule has a dayOfWeek sub-element.

schedule

Name

Values

Description

dayOfWeek

1, 2, 3, 4, 5, 6, 7, or comma-separated list of integers 1 through 7

The day or days of the week when the newsletter will be automatically sent. The dayOfWeek includes a number attribute, where the number can be a single digit, representing one day of the week.

1 - for Monday delivery
2 - for Tuesday delivery
3 - for Wednesday delivery
4 - for Thursday delivery
5 - for Friday delivery
6 - for Saturday delivery
7 - for Sunday delivery

or a comma-separated list of integers, e.g. if the number value is 1,3,5 this represents Monday, Wednesday, and Friday.

The dayOfWeek element displays different sub-elements depending on the defined schedule type. If the type is:

period - there will be startTime, endTime and periodInSeconds sub-elements.
settime - there will be a setTime sub-element.

dayOfWeek

Name	Values	Description
endTime	Thhmmss-hhmm	Indicates the time after which no more periodic newsletters are sent for the day. Time is in hours minutes and seconds with an offset from Greenwich Mean Time.
periodInSeconds	PTmmM	Indicates the time in minutes between the executions of periodic newsletters during a day.
setTime	Thhmmss-hhmm	Indicates a specific time of the day the newsletter will be sent. Time is in hours minutes and seconds with an offset from Greenwich Mean Time.
startTime	Thhmmss-hhmm	Indicates the time when this periodic newsletter is scheduled to start for the day. Time is in hours minutes and seconds with an offset from Greenwich Mean Time.

newsletter/deleteschedule - Delete a newsletter schedule

Use newsletter/deleteschedule to delete the newsletter schedule. See also api/info where noun=newsletter and verb=deleteschedule.

Example

https://secure.newsedge.com/opensapi/20/newsletter/deleteschedule?session=<<user-token>>&newsletter=<<newsletter-id>>&schedule=<<schedule-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
schedule		The scheduleID value returned from the newsletter/addschedule API or the schedule ID attribute value returned by the newsletter/info API.
session		The ID of the OPENS API session. Use the user-token value returned from the session/login request.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results include an opens-api element with a status and schedule sub-elements.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error.

newsletter/delete - Delete a newsletter

Use the newsletter/delete API to delete a saved newsletter. See also api/info where noun=newsletter and verb=delete.

Example

https://secure.newsedge.com/opensapi/20/newsletter/delete?session=<<user-token>>&newsletter=<<newsletter-id>>[&parameter=value]

Required Parameters

Parameter	Values	Description
newsletter		A numerical identifier representing the newsletter. Use the newsletter value from the original newsletter/create results or the id attribute for the newsletter from the newsletter/list call.
session		The ID of the OPENS API session. Use the value returned in the user-token element from session/login.

Optional Parameters

Parameter	Values	Description
json	Default:0 0,1,2	The json parameter controls the format of the return data. If the parameter is not provided, the data is returned in XML format. 0 - Return data in XML format. 1 - Return data in compact JSON format. If the caller is planning on using JSON in production, this value should be used. 2 - Return data in expanded JSON format. This parameter value sets the return data to be in a more human-readable JSON form.

Returned Results

The returned results from newsletter/delete include an opens-api element that contains a status sub-element.

opens-api

Name	Values	Description
status	OK, ERROR	The status of the request. OK - Request completed successfully. ERROR - An error occurred with the request. An error element contains a description of the error. For example: this error message indicates the API user does not have sufficient rights to delete the requested newsletter. <error>INVALID PUBLISHER LEVEL</error>

API Definition

Publishing Newsletters

newsletter/create - Build a newsletter

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletter/list - List newsletters

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletters

newsletter/info - Get newsletter details

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletter/update - Update a newsletter

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletter/addsection - Add a section to the newsletter

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletter/getsection - Retrieve the newsletter section configurations

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletter/updatesection - Configure and modify a newsletter section

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletter/deletesection - Delete a newsletter category

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletter/preview - Prepare to preview the newsletter

Example

Required Parameters

Optional Parameters

Sample storyxml:

Returned Results

opens-api

newsletter/checkpreview - Get the URL to preview your newsletter

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletter/addemail - Add a newsletter recipient

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

newsletter/getemaillist - Get the newsletter recipient emails

Example

Required Parameters

Optional Parameters

Returned Results

opens-api

emailList

newsletter/deleteemail - Delete a newsletter recipient

Example

Required Parameters