PoliteMail API

The PoliteMail API is an ODATA Service using the RESTful architecture

The PoliteMail Server application provides an Application Programmers Interface (API) which allows you to create programs to utilize PoliteMail functions, without the PoliteMail for Outlook client.

Common uses include uploading lists and content (templates), sending tracked email, or downloading email metrics reports for display or use in other applications.

The API supports standard HTTPS methods (e.g. GET, PUT, POST, DELETE).

The media type used is often JSON, but can be any other valid Internet media type (e.g. XML, Atom, etc.).

Once the API Service is activated for your account, the base URI for accessing the PoliteMail API will be: https://(YourPoliteMailServer)/ssv3/

Note that the ODATA functionality also enables you to connect to PoliteMail data using Excel PowerView or PowerBI.

To connect to your PoliteMail server via ODATA use:
https:// (Insert PoliteMail Server Name) /ssv3/odata

Service metadata can be viewed at:
https:// (Insert PoliteMail Server Name) /ssv3/odata/$metadata

See the PoliteMail API Entity Directory for documentation.

Using Trackable Smart Attachments (v4.5)

Attaching a file through the Outlook attach function can slow your send process considerably, particularly when sending to lists. In addition, large file attachments and certain file types make it more likely your email will be blocked or not delivered to a recipient’s mail server. The PoliteMail Smart Attachment feature overcomes these issues and enables you to track attachments to know who is opening your files.

A Smart Attachment will be placed into your email as a link, keeping your email size small and fast. The file is uploaded to the Content Library within your PoliteMail account and sent to your recipients. Like a regular file attachment, your recipient clicks the file name within the email to open it. When your recipient opens the Smart Attachment, PoliteMail will track the open.

Here’s how to include a Smart Attachment within an email message or template:

1. Within Outlook’s email editor, place the cursor where you want the file.

2. Click Smart Attachments > Smart Attachment. Find the file you would like to use (a PDF file or any Office document less than 10MB in size. The Smart Attachment maximum size limit is 10MB) from your computer and click Open.

Smart Attachment Icon

3. The file will upload and appear in the body of the message as a link. It will be saved automatically in the Content Library within the Smart Attachments folder. You will also be able to access your saved files for easy reuse by clicking on the Smart Attachments icon in an email message.

Content-Smart Attachments

4. When the recipient clicks the smart attachment link, you will receive tracking data that shows they opened the file. You will see this information on your message results screen in the Click Details section.

Writing Outlook compatible HTML code for email pages

Custom coding HTML pages to send via Outlook is NOT the same as coding a web page

Rules of the road for coding HTML pages to send in Outlook

First, understand that sending an HTML page to Outlook, is not the same as sending an HTML page from Outlook.

When you send HTML from Outlook, the Outlook editor (Word), is getting involved, and will rewrite your code.

The key to coding successful pages is understanding what Outlook is doing, and what code will actually work.

First, forget all your HTML5 and CSS techniques.

Code designed for modern browsers, and most CSS responsive design techniques, will not work properly.

Outlook uses Word to both render/display HTML, and to send it. When you put HTML code into the Outlook editor (for example, using IE > Send Page as Email or PoliteMail > Import HTML) Outlook will add Word (RTF) compatibility code, and will replace any CSS styles in the header with its own.

A benefit of this is you can copy and paste back and forth between Word and Outlook, and they will essentially work (although you will likely need to set your page margins to zero in Word for the layout not to fall apart).

Using the following coding rules will get you better results in Outlook, and in most other email programs being sent to (note that Outlook Online (OWA) and gmail tend to add extra space after a table cell).

  • Use inline styles, not CSS styles defined in the head of the page.
    In other words, you have define style tags on each element, and not rely on a class
  • Use table structures, not divs.
  • Do not use float (won’t work)
  • Fixed widths will yield more reliable rendering than percentage widths
  • Do not use background-image tags (won’t work)
  • If you don’t specify it, Outlook will include an alt, width and height on all img references.
    If you want an image to be a relative size or responsive, then place it inside a relative table structure, and set the img alt= tag to “mo_re100%”, and PoliteMail will modify the image specification on send
  • Any adjoining table cells td must contain the same identical padding (otherwise, Outlook will force it in and/or the page rendering will go astray).

    To achieve the spacing you want, you may embed a table inside the adjoining td, and add the padding to the inner td

  • Keep table structures limited to 3 nested tables.
  • If you are going to align images (left/right or center), limit them to 3 inside any one table.
  • For tables with long content that extends more then a tabloid printed page size (~23-24 inches) you will likely see unintended or unusual white space (breaks) in the page where you didn’t want it. This is some sort of Outlook/Word rendering bug, and the best way to avoid it is avoid long table cells, and use a series of stacked tables instead. If you are using an Outlook table structure with two td columns, and long content inside, you will likely need to redesign the page to have that side column broken up into separate pieces.