Send Email to KanBo - Installation (Cloud)
The Send Email to KanBo feature will allow you to send emails directly to a KanBo Board and create a new Card out of the email. It will also allow you to add email and its attachments to an existing KanBo Card.
- This feature is enabled for KanBo in version 2.7 or higher.
- Functionality requires having a service account on your Office 365 to serve as a Catch-All account. This Office 365 user needs to have at least Exchange Online license.
- You should set up an email account for Incoming Email with a custom domain. Learn how to add a custom domain to your Office 365 here: Add a domain to Office 365. When you wish to proceed with a custom domain, create a service account with this domain in his email address (example: [email protected])
1. Creating a Catch-All email address.
You will need to create a Catch-All email account in your Exchange Online.
- Read how create a Catch-All email address here.
- Read more about Catch-All address and how to create it on Exchange here.
This is a recommended scenario for creating a Catch-All address for Office 365/Exchange Online.
- Create a new account for the Catch-All purpose only in Office 365 Admin Center. Give this account the Exchange Online license. Read more here about assigning Office 365 licenses to users here.
- Add accepted domain in your Office 365.
Go to Office 365 and select Admin -> Exchange. As a next step, please choose the Email Flow in Exchange Admin Center.
- Click on the “Accepted Domains”, then select your domain and click on the edit button.
- In the new windows, change “Authoritative” to “Internal Relay” and save the changes.
- Open Mail Flow section once again. Now select the Rules section and click on + (Add New button) and chose Create New Rule.
- When the rule appears, select "More options..." at the bottom of the page. Give this Rule a name like "CatchAll".
- Set the following properties to the Rule.
- In Apply this rule if chose "A recipient's domain is" - here add your domain.- In Do the following chose "Redirect the message to" and then, chose your CatchAll Email account from the User Picker.- In Do the following Add Action and select "Set the message header to this value..." and "Set the message header 'X-CatchAll-Rule' to value 'Yes'.- In Except if... select "The recipient is..." and then, chose your CatchAll Email account from the User Picker.
Now save the Rule.
2. SSL certificate and its configuration
- Create a pair of certificates using Makecert or Powershell.
- Upload the certificate to Azure in your Azure App -> TLS/SSL settings -> Private certificates -> Upload Certificate..
- Go to your App's Configuration and add a new setting. It should be called WEBSITE_LOAD_CERTIFICATES and the value should be the thumbprint of your certificate.
- Go to https://yourkanbo.scm.azurewebsites.net -> Debug Console -> Powershell -> Site, create a directory called Certs or Certificates and upload your certifiate pair there. To upload certificates, pack them all in a .zip file and drag*drop on the left side of Kudu editor.
- Go to https://yourkanbo.scm.azurewebsites.net -> Debug Console -> Powershell -> Site ->wwwroot and start editing the web.config. Add the following code before </plugins> section of web.config of KanBo.
Change the thumbprient of the certificate in value field.
<auth.app issuer="incoming-mails"> <signature algo="rs256"> <cert type="x509-store" store-name="my" store-location="currentuser" key="thumbprint" value="thumprint-value" valid-only="false" /> </signature> <mapper type="service" name="incoming emails" roles="service" /> <mapper type="user" roles="external-services"></mapper> <mapper type="email" roles="service" /> <mapper type="login" /> </auth.app>
- Move slightly to the bottom to see the <appSettings> section.
- Set KanBoIncomingMail value to true.
<add key="KanBoIncomingMail" value="true" />
- Set KanBoIncomingMailDomain to your sending domain name - the one on which you have the Catch-All mailbox.
<add key="KanBoIncomingMailDomain" value="YourDomain" />
Save the web.config.
4. Configure permissions
Go to Azure AD and find App registrations. Find the registration for your KanBo.
Make sure to write down the values, because they will be needed in the next step.
Overview - take Application (client) ID and Directory (tenant) ID.
Take the Thumbprint of the certificate in the Certificates and Secrets section.
Go to API Permissions and select Add a permission.
Select Microsoft Graph.
Select Delegate and the following permisisons.
- OpenID permissions - Email
- Mail - Mail.Read and Mail.ReadWrite
Save it. Follow the process, this time select Application permissions.
Here add Mail - Mail.Read and Mail.ReadWrite
Once added, grant Admin's consent.
5. Configure the Email Tool
Contact us at [email protected] to receive an Email to KanBo tool package.
- Once you download the package, unzip it and move it a chosen location.
- Open your directory and start editing EmailToKanBo.exe.config
- In the following section please change the following values:
- [email protected] - add here your Catch-All email
- Password - add here the Catch-All account's email
<add key="mail.type" value="azure-unread-cert-thumb"/> <add key="mail.receiver-email" value="[email protected] "/> <add key="mail.receiver-password" value="Password" />
- In the next section, adjust the following values:
- CertPath - local path to your certificate (in Azure it will be like: D:\home\Certs),
- Password - your certificate password,
- https://YourKanboAddress - add here your KanBo address
- YourDomain - add here your email domain to which Catch-All address is connected to
<add key="kanbo.incoming-mail-domain" value="YourDomain" /> <add key="kanbo.api.url" value="https://YourKanboAddress" /> <add key="kanbo.api.issuer-base" value="incoming-mails" /> <add key="kanbo.api.cert.file" value="CertPath" /> <add key="kanbo.api.cert.pass" value="Password" />
- Now let's configure the last part:
KanBoThumbprint - Thumbproient of the certificate from KanBo web.config which is used to communicate with Azure AD. You can take the thumbprint from the Certificates &secret section of the Azure app registration.
App-ID - App Id from the KanBo web.config. You can use Application (client) ID from Azure AD app registration too.
Tenant-ID - Tenant ID from the KanBo web.config. You can use Directory (tenant) ID from Azure AD app registration too.
<add key="mail.cert-thumb" value="KanBoThumbprint" /> <add key="mail.store-name" value="My" /> <add key="mail.store-location" value="CurrentUser" /> <add key="mail.app-id" value="App-ID" /> <add key="mail.azure-realm" value="Tenant-ID" />
Save the changes.
TIP: If you intend to send emails to your catch-all address and some other email addresses (multiple at once), add this entry and adjust the number inside it to match the maximum number of receivers.
To use bcc and cc addresses, extend the value.
<add key="kanbo.max-receivers" value="1" />
6. Add an Azure App Webjob
- Pack the EmailToKanBo folder in a .zip file (the package you were working on in the previous steps).
- Go to your Azure App -> Webjobs. Select +Add.
Name: yuour custom name
File upload: the .zip of EmailToKanBo package, already configured,
CRON Expression: choose the convenient time for you, for information regarding CRON on Azure, see this guide.
7. Use it!
You finished the configuration and installation of the Incoming Mails feature.
Now read how to use this feature by reading an article here: Incoming Emails
Recommendation: Set an Outlook retention policy to remove old messages
In order to not allow your Incoming Mails mailbox to clog up, set a simple rule to clean messages older than a week.
1. As Exchange Administrator, got to Exchange Admin Center -> Compliance Management -> Retention Tags. Create a new rule "applied automatically to a default folder.
2. Find out a name, select this tag to apply to Inbox only and choose retention period to 90 days.
3. Go to retention policies and create a new Retention policy with this retention tag assigned.
4. Go to recipients, select your Incoming Mails account and then in Mailbox features select your newly created Retention Policy.