SharePoint 2013/Online: Send Email Using REST API

Sending Email is one of the most common functionalities that need to be developed in almost every project irrespective of the nature of the project.

Based on the new development paradigms introduced by Microsoft, recommended development approach prefers to make use of Client Side Object Model and REST API for developing functionalities for SharePoint 2013.

In this article by moving on the same lines we will discuss how to develop a Mail Client for SharePoint Online/2013 using REST API End Point exposed by SharePoint 2013.

In this demo I will make use of OOB Content Editor WebPart for executing the Javascript Code and a virtual mail Utility “smtp4dev” which is available on CodePlex for free download. “smtp4dev” allow you to test mail functionality by intercepting incoming mails using a thin mail client by configuring a local SMTP Server in your development VM.

I have mentioned quite a number of such useful tools in one of my earlier blog post SharePoint Developer Tools – Get Your Gears, and recommend you to visit it for details on the tools that can be very helpful in enhancing developer productivity while working in SharePoint Environment.

Let’s start by writing JavaScript code and since we are making use of Content Editor WebPart we need to perform some additional tasks:

  • Open SharePoint Designer
  • Visit Site Assets Library
  • Add a new Text file and give it a proper name of your choice

1

In the text file add the code as shown in the following steps

Step 1: CSS of your choice to build the UI as desired. In my case I put some CSS classes for the UI of mail client

2

Step 2: Add some HTML elements that design the UI for the Mail Client and apply CSS classes appropriately

3

Step 3: Add reference to “jquery.js”, “sp.runtime.js” and “sp.js” files

4

Step 4: Add “document.ready” function to bind the click even of the button with the appropriate event handler

5

Inside Event Handler function “SendMail ()” we will proceed with the code as follows:

Step 5: Reading values from UI control to prepare the Email Contents to be sent

Step 6: Preparing the Request Header object to be sent along with REST API call to SharePoint, this object is necessary to provide execution details to be authenticated by SharePoint

Step 7: Preparing REST API URL to pass into the subsequent call by making use of page context variable

Step 8: Preparing API Call by configuring metadata object of type “SP.Utilities.EmailProperties”. It is worth to spend time to review this object for a while to notice what all properties are exposed by this object. We can specify From Email, To Email, CC Email, Subject & Body of the mail with in this object

Step 9: In the success call back we can perform the desired action, in this demo we are just writing down a success message to the Result Panel

6

With this we are all done with coding and now it is time to create a new page and add Content Editor WebPart to the page

  • Go to Site Page Library
  • Add a new WebPart Page
  • On the WebPart Page, Click Add WebPart Link

7

  • From the WebPart Picker choose “Content Editor” WebPart that falls under “Media and Content” category
  • Click Add to add the WebPart to the Page

8

Next thing is to add the reference to the JavaScript Code file that we have created in the steps above.

  • To refer the Code file Edit the WebPart
  • Specify the relative URL of the Code file in the Content Link placeholder in WebPart Properties as shown below

9

10

  • Once done with the changes choose “Stop Editing” from the Ribbon to save the changes to the WebPart

11

If the code executes successfully we will see the UI for Mail Client rendered as shown below

12

Before we execute the code to send the mail we need to first have a look to the “smtp4dev” tool. This tool will receives the mail messages and get them displayed to “Messages” Tab

13

Now enter the Name, Email Address and Message on the UI and click “Send Email” button

14

Once the Email functionality gets executed successfully, we will see the Success message print in the Result Panel and also an Email Received Notification from “smtp4dev” tool.

15

We can analyze the received further by looking it into the “smtp4dev” tool “Message” Tab.

In the “Message” Tab select received mail and click on the “Inspect” button

16

On the “Message Details” screen under the “Body” Tab we can see the body of the mail received

17

Since this the REST call we can analyze the corresponding Request-Response cycle using any Web Proxy tool, here I am using Fiddler to inspect it.

We will get a null response Object in case of successful execution of the Email functionality.

18

Known Limitations

Issue with Attachments

Adding attachments with in the Email is not supported using this approach and this limitation is due to limited exposure of the properties by “SP.Utilities.EmailProperties” Object.

Only following properties has been exposed by this object to be used with in REST Call

19

Here we can see that there is no property exposed for adding attachments along with the mail.

Issue with External Mails

External Mail are not supported using this approach which means we can only send mails to valid Site Users only if you try to send the mail to any external User or Email ID you will probably get the following error:

20.png

That is all for the demo.

Hope you find it helpful.

 

Advertisements

6 thoughts on “SharePoint 2013/Online: Send Email Using REST API

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s