-->
The functionality works fine in Office 365 Online and Outlook for Windows. However, when I sign in from Outlook 2016 for Mac, the Azure AD auth works only for the first time. When I click the web add-in icon on the top ribbon, the User.Identity.IsAuthenticated property turns out to be false. This issue is reproducible only on Outlook for Mac. With Outlook on your PC, Mac or mobile device, you can: Organize your email to focus on the messages that matter most. Manage your calendar to schedule meetings and appointments.
Outlook add-ins are integrations built by third parties into Outlook by using our web-based platform. Outlook add-ins have three key aspects:
- The same add-in and business logic works across desktop (Outlook on Windows and Mac), web (Office 365 and Outlook.com), and mobile.
- Outlook add-ins consist of a manifest, which describes how the add-in integrates into Outlook (for example, a button or a task pane), and JavaScript/HTML code, which makes up the UI and business logic of the add-in.
- Outlook add-ins can be acquired from AppSource or sideloaded by end-users or administrators.
Outlook add-ins are different from COM or VSTO add-ins, which are older integrations specific to Outlook running on Windows. Unlike COM add-ins, Outlook add-ins don't have any code physically installed on the user's device or Outlook client. For an Outlook add-in, Outlook reads the manifest and hooks up the specified controls in the UI, and then loads the JavaScript and HTML. The web components all run in the context of a browser in a sandbox.
The Outlook items that support add-ins include email messages, meeting requests, responses and cancellations, and appointments. Each Outlook add-in defines the context in which it is available, including the types of items and if the user is reading or composing an item.
Note
When you build your add-in, if you plan to publish your add-in to AppSource, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).
Extension points
Extension points are the ways that add-ins integrate with Outlook. The following are the ways this can be done:
- Add-ins can declare buttons that appear in command surfaces across messages and appointments. For more information, see Add-in commands for Outlook.An add-in with command buttons on the ribbon
- Add-ins can link off regular expression matches or detected entities in messages and appointments. For more information, see Contextual Outlook add-ins.A contextual add-in for a highlighted entity (an address)
Note
Custom panes have been deprecated so please ensure that you're using a supported extension point.
Mailbox items available to add-ins
Outlook add-ins are available on messages or appointments while composing or reading, but not other item types. Outlook does not activate add-ins if the current message item, in a compose or read form, is one of the following:
- Protected by Information Rights Management (IRM) or encrypted in other ways for protection. A digitally signed message is an example since digital signing relies on one of these mechanisms.
- A delivery report or notification that has the message class IPM.Report.*, including delivery and Non-Delivery Report (NDR) reports, and read, non-read, and delay notifications.
- A draft (does not have a sender assigned to it), or in the Outlook Drafts folder.
- A .msg or .eml file which is an attachment to another message.
- A .msg or .eml file opened from the file system.
- In a shared mailbox, in another user's mailbox, in an archive mailbox, or in a public folder.
- Using a custom form.
In general, Outlook can activate add-ins in read form for items in the Sent Items folder, with the exception of add-ins that activate based on string matches of well-known entities. For more information about the reasons behind this, see 'Support for well-known entities' in Match strings in an Outlook item as well-known entities.
Supported hosts
Outlook add-ins are supported in Outlook 2013 or later on Windows, Outlook 2016 or later on Mac, Outlook on the web for Exchange 2013 on-premises and later versions, Outlook on iOS, Outlook on Android, and Outlook on the web in Office 365 and Outlook.com. Not all of the newest features are supported in all clients at the same time. Please refer to articles and API references for those features to see which hosts they may or may not be supported in.
Get started building Outlook add-ins
To get started building Outlook add-ins, try the following.
- Quick start - Build a simple task pane.
- Tutorial - Learn how to create an add-in that inserts GitHub gists into a new message.
See also
Reading Time: 6minutesPre-Flight Check
- These instructions are intended specifically for setting up a new email account in Microsoft Outlook 2016 for Mac OS X 10.11.3.
- If you have not already created an email address on your server, visit our New User Tutorial: Creating E-Mail Addresses in cPanel.
- If you need to configure your email address in Outlook 2016 for Microsoft Windows, see How To Set Up Email in Outlook 2016. For other mail clients, check out our tutorial on setting up other email clients.
Step #1: Add or Edit the Email Account
- To set up a new email account or edit the settings on an existing one, click the Tools menu and then select Accounts to open the Accounts panel.
- The setup process is slightly different depending on whether you have any existing email accounts configured in Outlook 2016:
- Setting up your first email account: If this is your first time setting up Outlook 2016, you will need to click on the envelope icon next to the third option: Other Email (iCloud, Google, Yahoo!, or other accounts):
- Setting up an additional email account: Once any email account has been set up in Outlook 2016, additional accounts can be added by clicking the plus sign in the lower left corner and selecting Other Email… from the pull-down menu:
- Changing the settings for an existing email account: Click on the account’s name in the account list on the left to make changes to any existing account in Outlook 2016, and skip ahead to Step #4: Editing an Existing Email Account.Note: You cannot edit an existing email account to directly change its connection method. To change an account from POP to IMAP or vice versa, simply add a new account for the email address as described below and select the desired connection type. Outlook 2016 will allow you to have multiple accounts for the same email address, so an account for [email protected] using IMAP can coexist with an account for [email protected] using POP. To prevent data loss, do not delete the existing account before adding a new one.
Step #2: Configuring a New Email Account
On the account information panel, enter the information as follows:
At first, you will only see the E-mail address and Password fields. Once you enter your email address, Outlook 2016 will recognize that you’re not attempting to connect to a web service such as iCloud, Google, or Yahoo, and will automatically expand the window to reveal all the fields shown in the image above.
- E-mail address: requires your complete email address, such as [email protected].
- Password: is the password associated with the email account.
- User Name: is your full email address. It should exactly match what you entered into the E-mail address field above.
- Type: you may select IMAP or POP. IMAP is recommended for its ability to sync messages between multiple devices (to learn more about the difference between the protocols, see IMAP vs POP3 email).
- Incoming server:
- When using standard (non-SSL) settings, use mail.yourdomainname.com
- When using secure (SSL) settings, use the server’s hostname (host.yourdomainname.com)
- The default port numbers should not need to be changed unless you have configured your server to use non-standard ports (not common)
- Check the box next to Use SSL to connect (recommended)
- Outgoing server:
- When using standard (non-SSL) settings, use mail.yourdomainname.com
- When using secure (SSL) settings, use the server’s hostname (host.yourdomainname.com)
- The default port numbers should not need to be changed unless you have configured your server to use non-standard ports (not common)
- Check the box next to Use SSL to connect (recommended)
Once you’ve entered all the requested information, click the Add Account button at the bottom of the window to create the account with your specified settings.
Step #3: Configure Security Settings
When you add your email account, an alert window may prompt you to review security settings. This is expected if you have not already purchased and installed a signed, third-party verified SSL certificate on your mail server. If you see no such prompt, then you’re all set and can begin using Outlook 2016 with your email account immediately.
If you do get a security prompt, which specifies that information that you view and send will be encrypted, note that Outlook 2016 will not be able to verify the security of the certificate through a third-party because you are the only authority validating it:
If you wish to proceed with the connection, you have two options:
- You can click the Continue button to proceed, with the caveat that you may need to accept the warning each time Outlook connects.
- Or, you can permanently store the certificate and treat it as trusted, by clicking Show Certificate and then checking the box next to Always trust … before clicking Continue. You will need to authenticate with your password to store the exception for your self-signed certificate.
Note: A self-signed certificate uses the same level of encryption as a third-party verified certificate; the difference is that it is you who are verifying your server’s identity and not a third party who is paid for the service. However, if you would prefer to use a third-party verified SSL certificate to cover core services (cPanel/WHM, POP3, IMAP, SMTP and FTP) on your server, you can find instructions for ordering and installing an SSL certificate at Install an SSL Certificate on a Domain using cPanel, and you’ll find a guide to installing your certificate on email and other core server services at Installing Service SSLs in cPanel. Should you find that you need any assistance, please feel free to contact a Heroic Support® technician who can assist with obtaining and installing an SSL from the vendor of your choice.
Once connected, Outlook 2016 will download your mail from the server along with any custom directories you’ve added, which will be synced by default.
Step #4: Editing an Existing Email Account
To change the settings on an existing email account, click the Tools menu and then select Accounts to open the Accounts panel.
Click on the name of the account in the left pane, and make the desired changes:
- User Name: is your full email address. It should exactly match the value of the E-mail address field above.
- Password: is the password associated with the email account.
- Incoming server:
- When using standard (non-SSL) settings, use mail.yourdomainname.com
- When using secure (SSL) settings, use the server’s hostname (host.yourdomainname.com)
- The default port numbers should not need to be changed unless you have configured your server to use non-standard ports. If you do need to configure mail on a different port, you can check the box next to Override default port and enter the appropriate incoming mail server value (POP3 should be 110 for non-SSL connections and 995 when using SSL; IMAP should be 143 for non-SSL connections and 943 when using SSL.)
- Check the box next to Use SSL to connect (recommended) for a secure connection.
- Outgoing server:
- When using standard (non-SSL) settings, use mail.yourdomainname.com
- When using secure (SSL) settings, use the server’s hostname (host.yourdomainname.com)
- The default port numbers should not need to be changed unless you have configured your server to use non-standard ports. If you do need to configure mail on a different port, you can check the box next to Override default port and enter the appropriate outgoing mail server value (25 for non-SSL connections and 465 when using SSL; Unlike many other mail clients, Outlook 2016 does not require you to use port 587 on Mac OS X).
- Check the box next to Use SSL to connect (recommended) for a secure connection.
- The More Options… button will allow you to configure authentication for the outgoing (SMTP) mail server:
- Authentication: Typically, Use Incoming Server Info is sufficient, but if you receive connection errors due to SMTP authentication, you may need to select User Name and Password. Do not select None; you will not be able to send mail if None is selected as the authentication type.
- User Name: This field can only be filled in if you use the User Name and Password authentication type. If enabled, it must be the full email address.
- Password: This field can only be filled in if you use the User Name and Password authentication type. If enabled, use the email account’s password.
Bonus: Select IMAP Folders to Sync
By default, Outlook 2016 for Mac OS X will sync all IMAP folders. To specify which ones you want to sync, pull down under the Tools menu and select IMAP Folders… to bring up the Folder Browser.
In the Folder Browser, you will see a list of your accounts in the left pane.
- In the first pane, click on the IMAP account’s name
- In the second pane, click on INBOX (or the desired custom folder, if listed)
- In the third pane, click on the folder to which you want to subscribe or unsubscribe.
- Folders to which you already are subscribed will be displayed in bold type, while folders to which you are not currently subscribed will be displayed in a light-face font. Note that on some versions of Mac OS X, the distinction can be almost imperceptible.
- Clicking on the name of a folder to which you are subscribed will allow you to click the red ( – ) Unsubscribe button in the top-left menu, and clicking on the name of a folder to which you are not subscribed will allow you to click on the green ( + ) Subscribe button in the top-left menu.
- You can not unsubscribe to default account folders, such as Drafts, Junk, Sent, and Trash.