How to Get Office 365 Mail Attachments using SSIS

Contents hide

1 Introduction

2 Prerequisites

3 Use Case of Microsoft Graph API

4 Register Application (OAuth2 App for Graph API)

5 Step-By-Step to Call Microsoft Graph Rest API Using SSIS

5.1 Configure SSIS OAuth Connection for Graph REST API

5.2 Download the Messages Attachment Files from Outlook

6 Conclusion

7 References

7.1 More from ZappySys Blog

Introduction

NOTE: UPDATE: ZappySys has released a brand new API Connector for SSIS Outlook Mail (Office 365) which makes it much simpler to download attachment, read / search Emails, Users, MailFolders, Send email and more in SSIS compared to the steps listed in this article. You can still use steps from this article but if you are new to API or want to avoid learning curve with API then use newer approach.

Please visit this page to see all Pre-Configured ready to use API connectors which you can use in SSIS API Source / SSIS API Destination OR API ODBC Driver (for non-SSIS Apps such as Excel, Power BI, Informatica).

In our previous article, we saw How to Get Office 365 data in Power BI. Now let’s look at How to Get Office 365 Mail Attachments using SSIS without any coding. Microsoft Graph API is a unified way to access many Microsoft services API including Office 365 API. In this post, we will use SSIS JSON / REST API Source Connector to get the Outlook Messages list and get the attachments of those messages.

Prerequisites

Before we perform the steps listed in this article, you will need to make sure the following prerequisites are met:

SSIS designer installed. Sometimes it is referred to as BIDS or SSDT (download it from the Microsoft site).
Basic knowledge of SSIS package development using Microsoft SQL Server Integration Services.
Make sure ZappySys SSIS PowerPack is installed (download it, if you haven't already).
(Optional step). Read this article, if you are planning to deploy packages to a server and schedule their execution later.

Use Case of Microsoft Graph API

Here are some use cases why you want to use Microsoft Graph API

Read/Write events from Outlook Calendar
Send email / Read emails
Get the list of files from OneDrive
Upload/ Download files to OneDrive
Read/Write Excel Sheet (Use range or a specific range of specific sheet)
Read Sharepoint Document library
Search content from Sharepoint document library
Get AD users for your Organization (AD Accounts)
Update OneNote
Track changes to Users, Events, Calendar Items using delta API

Register Application (OAuth2 App for Graph API)

The first step to access any Office 365 API / Graph API is to register an OAuth App in the Azure Portal. After following these steps, you will get the following two items to use in the next section:

Application Id
Application Secret

In this section, you will learn how to register a custom app in Microsoft Azure portal that will allow access to the OneDrive. So, let's get started -

Log into Microsoft Azure portal to register a custom app.
Register a new application by clicking New Registration link.
Provide the name of the custom app and who can access the app in the organization.
Go to the App overview and add a Redirect URL.
Click on "Add a Platform" under Platform Configuration section and then select "Web" under Web applications section to enter a Redirect URL.
```
https://zappysys.com/oauth
```
Create a Client Secret key which will be used to Authenticate the custom Azure app.
Note - Take a note of Client Secret, it will be required while configuring OAuth connection in the SSIS later
Add API Permissions.
Select following permissions from the Delegated Permissions section.
```
User.ReadBasic.All
Files.Read
offline_access
```
Take a note of Client ID, it will be required while configuring OAuth connection in the SSIS later.

Step-By-Step to Call Microsoft Graph Rest API Using SSIS

Now let’s look at examples to access your outlook.com emails using SSIS. You can use the same techniques to call pretty much any Office 365 API.

Configure SSIS OAuth Connection for Graph REST API

The first step to access any Graph API is configured OAuth connection

Open Visual Studio
Open existing SSIS Project or create new using File > New > Project > Choose “Integration Services Project” Type under Business Intelligence template category
Create Package
Right-click inside the Connection Managers area and click “New Connection…”
From the connection type list select “ZS-OAUTH” connection type.
Create new SSIS OAuth API Connection Manager
On the OAuth, Connection Manager configure the following options
1. Select “Custom” from Provider dropdown
2. Select OAuth2 from OAuth version
3. Enter your Application Id and Secret Key (i.e. App Password) obtained in the previous section from here.
4. Enter the following URL in the Authorization URL
  
  https://login.microsoftonline.com/common/oauth2/v2.0/authorize
  
  1
  
  https://login.microsoftonline.com/common/oauth2/v2.0/authorize
5. Use following URL in the token URL field
  
  https://login.microsoftonline.com/common/oauth2/v2.0/token
  
  1
  
  https://login.microsoftonline.com/common/oauth2/v2.0/token
6. Enter the following Graph API Scopes (each scope must be entered in a new line).
  
  user.read mail.read offline_access
  
  1
  2
  3
  
  user.read
  mail.read
  offline_access
  
  NOTE: Always include offline_access scope returns refreh_token which allows you to renew token without going through the login process again. For more information about which scopes needed always refer to the API help page (e.g. if you want to read mail using this API then you will see it says you can use Mail.Read or Mail.ReadWrite scope).
7. Go to Advanced tab and enter the following URL in the Callback/Return URL (Assuming exact same URL used when you registered App in the previous section)
  
  https://zappysys.com/oauth
  
  1
  
  https://zappysys.com/oauth
8. Now go back to the first tab and click Generate Token. When prompted Login using your Personal Microsoft Account or Work Account (Office 365 or AD login)
9. After login, you will see Accept option just click it. If things go right then you will see Access Token and Refresh Token fields will be populated.
Once all configured you can click Test to make sure connection works.
SSIS OAuth Connection Manager for Office 365 REST API / Microsoft Graph API

NOTE: Typically RefreshToken is longed lived but in some cases, they may expire soon too. If that’s the case then you can configure above OAuth connection for Changing RefreshToken pattern. Simply enter the token file path and re-authenticate by clicking Generate Token. After that each time you make an API call it will save a new refresh token in the file.

Download the Messages Attachment Files from Outlook

Let’s start with an example. We use the SSIS JSON Source and Web API Destination components to make the call to Microsoft Graph Rest API.

First of All, Drag and drop Data Flow Task from SSIS Toolbox and double click it to edit.
Drag and Drop : Data Flow Task from SSIS Toolbox
From the SSIS toolbox drag and drop JSON Source on the data flow designer surface.
Drag and Drop JSON Source Component
Double click JSON Source and enter the following URL as below to Get Messages API call with search options to get the mails which have the attachments.

https://graph.microsoft.com/v1.0/me/messages?$select=sentDateTime,from,subject,hasAttachments&$search="hasAttachments:True"

1

https://graph.microsoft.com/v1.0/me/messages?$select=sentDateTime,from,subject,hasAttachments&$search="hasAttachments:True"

Set the filter as $.value[*] and click on the preview.
SSIS JSON Source – Get data from Microsoft Graph API (Office 365 API – Read Mail Example)

To customize URL with additional parameters check this help link. It’s a standard OData Protocol so you can leverage many common OData features (e.g. Use $top parameters to set pageSize. Default is 10 for List Mail but you can include more records per response by changing it such as …/messages?$top=50).
Now let’s use Template Transform to set the URL using the message ID to make the Get attachment API call.

https://graph.microsoft.com/v1.0/me/messages/<%id%>/attachments

1

https://graph.microsoft.com/v1.0/me/messages/<%id%>/attachments

SSIS Template Transform
Now we need to use Web API Destination to make the Get Attachment API call by message-id. Select the Input column for URL as that TemplateOutput.
SSIS Web API Destination – Get data from Microsoft Graph API (Office 365 API – Get Attachment Example)

Now next step is to parse the JSON Response String of get attachment api call, for that we need to use JSON Parser. Select the input as Web PAI Destination ResponseText and use the below sample JSON string to configure the metadata(Columns).

{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('support%40zappysys.com')/messages('AQMkADAwATMwMAItMDkyMC0zZTg4AC0wMAItMDAKAEYAAAP_JUy')/attachments"
,"value":[{"@odata.type":"#microsoft.graph.fileAttachment","@odata.mediaContentType":"text/plain"
,"id":"AQMkADAwATMwMAItMDkyMC0zZTg4AC0wMAItMDAKAEYAAAP_JUy_27M"
,"lastModifiedDateTime":"2020-02-21T07:36:16Z"
,"name":"Test.txt","contentType":"text/plain","size":870,"isInline":false
,"contentId":null,"contentLocation":null,"contentBytes":"VGVzdCBNZXNzYWdl"}]}

{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('support%40zappysys.com')/messages('AQMkADAwATMwMAItMDkyMC0zZTg4AC0wMAItMDAKAEYAAAP_JUy')/attachments"

,"value":[{"@odata.type":"#microsoft.graph.fileAttachment","@odata.mediaContentType":"text/plain"

,"id":"AQMkADAwATMwMAItMDkyMC0zZTg4AC0wMAItMDAKAEYAAAP_JUy_27M"

,"lastModifiedDateTime":"2020-02-21T07:36:16Z"

,"name":"Test.txt","contentType":"text/plain","size":870,"isInline":false

,"contentId":null,"contentLocation":null,"contentBytes":"VGVzdCBNZXNzYWdl"}]}

JSON Parser Transform

Now in the JSON Parser go-to columns Tab and set the contentBytes DataType as DT_IMAGE and increase others’ columns DT_WSTR length with 1000 and 1500. We set contentBytes to DT_IMAGE datatype its like varbinary(MAX) .
JSON Parser Transform Columns Tab
Furthermore, on the next step, we need to use SSIS Derived Column to set the FilePath where we want to save the attachments and concat the local file path with the attachment name column.
SSIS Derived Column: Add New Column
Finally, we need to use the Export Column Transform (Native) to export attachment bytes to a local file. It needs to know 2 upstream info Bytes and Target File Path.
Export Column
Make sure to attach the export column to some destination (e.g. Our ZS Trash Destination) else it might be removed by the engine while It will optimize the runtime And it may remove all transformations that don’t have Destination like deploying the package to SQL Server or if you set optimize in the Visual Studio.
That’s it execute the package and it will download all the email attachments.
Downloaded Mail Attachments

Conclusion

After all, In this article, we have learned how to make Microsoft Graph API Rest API call. We used SSIS JSON / REST API Connector to extract data from Outlook Mail using OAuth. Made the Get attachment API call using the Web API Destination and parsed the JSON response using the JSON Parser. And using Native SSIS Export Column we saved export attachment bytes to a local file. To explore many other scenarios not discussed in this article download SSIS PowerPack from here (includes 70+ Components).

References

Finally, you can use the following links for more information:

- Help File: JSON Source(REST API or File)
- Help File: Web API Destination
- Help File: JSON Parser Transform
- Overview of the Microsoft Graph API