In this article:
1. Introduction
2. How to create new cards via email?
3. How to update existing cards via email?
1. Introduction
Creating and updating cards via email can be achieved through the Businessmap email integration feature.
All you need to do is send an email to an email-integrated user in Businessmap.
Such a recipient can be:
- A Businessmap email address that is configured as an email integration user in your Businessmap instance (example.kanbanize.com) e.g. support_example@kanbanize.com (please refer to scenario 1 from the dedicated article). The user needs to be a member of the board, on which the card is to be created/updated and needs to have sufficient permissions to create/update cards on that board.
- A custom domain email address that is configured as an email integration user in your Businessmap instance e.g. support@example.com (please refer to scenario 2 from the dedicated article). The user needs to be a member of the board, on which the card is to be created/updated and needs to have sufficient permissions to create/update cards on that board.
- The default notifications address for your instance (example.kanbanize.com) e.g. example_notifications@kanbanize.com.
Note: this option would only work for internal users i.e. members of the instance - if an external user (that is not registered as a member of your Businessmap instance) sends an email to the default notifications address, their email will not be processed, and a card will not be created.
Keep in mind that the card that is to be created will actually be created by the notifications address on behalf of the user that sends the email, so the user would need to specify the boardname (in the email subject) on which the card should be created. If the user is assigned to only one board or if they have a board set to auto-open, they can omit the boardname property from the subject.
2. How to Create New Cards via Email?
To create a new card via email, you have to format the text accordingly and specify the needed properties depending on your needs.
The subject of the email should contain the name of the board* where the card is to be created as well as the title of the card, while the email body will be used to define the new card's properties such as owner, column, priority, deadline, etc.
*The name of the board where the card is to be created should be surrounded by curly brackets. If omitted, the email integration user's default location for new cards will be used to create the card.
For example:
Subject: {Recruitment} Create an Assessment Report
Body: {#owner: Teo #column: Requested}
This email will create a new card on the board called “Recruitment” with a card title “Create an Assessment Report.” The card will be assigned to Teo and will be placed in the "Requested" column.
If you want to set more than one property, you need to follow the same format:
{#property1: value #property2: value #property3: value}
Building on the example from above, if you send an email with:
Subject: {Recruitment} Create an Assessment Report
Body: {#owner: Teo #workflowname: Reporting #lane: Default Swimlane #column: Requested #priority: high}
This will create a card in the designated location (board - Recruitment, workflow - Reporting), assign it to Teo, and set a high priority:
The card's history will show that it was created by email and when.
Important: The email body properties (e.g. title, description, owner, etc.) are not case-sensitive and you can use them in lowercase, uppercase, or capitalized.
Any email attachments from the email will be added to the newly created card, provided that the file format is permitted to be used.
Below is a list of properties that can be used when creating new cards via email.
- title – Title of the card. If omitted, the subject of the email is used as a title.
- description – The card's description. If omitted, the email body will be used as a description.
- customid - Set a custom card ID for the card that is to be created e.g. 12345.
- color – Choose a color for the new card by specifying the hex code of the color without the # sign.
- priority – Define the card's priority - it can be set to low, average, high, or critical.
- size – Specify the size of the card in accordance with the board's size type setting.
- owner – Set an owner on the card - must be a valid username of an active user in the instance.
- deadline – Deadline in any of the following formats: 2012-05-05, now, 10 September 2012, -1 day, -1 week 2 days, last Monday
- tags – Set a tag on the newly created card.
- external link or extlink – Set an external link value for the card. Note that this is a custom field that needs to be available on the board where the card is to be created.
- comment – Adds a comment to the card. There could be multiple comments.
- subtask – Adds a subtask or multiple subtasks. If you add @username, the subtask will be assigned to that person. For example, #subtask: This is subtask @username2
- column – If you have columns with the same names, you need to specify the complete path: Column.SubColumn.Subcolumn2. If there are no subcolumns defined, the path should read Column.Column. If this property is not set, the card is created in the backlog. If a card is to be created in a column and the limit of the column is to be exceeded, you need to set the property “reason”.
- lane – The swim lane the card is to be created into. If not set, the card is created in the first swim lane.
- workflowname - The workflow in which the card/initiative should be created.
- watcher - Set a watcher for the card, using either user name (#watcher: john) or user's ID (#watcher: 234)
- reason – Reason to exceed a limit.
- template – Apply a template on the card, e.g. {#template: template name}. Note that if the template contains linked cards, they will not be applied. Additionally, if you specify a name for the new card in the subject line of the email, that name will override the template name.
- custom field – Set a custom field on the card - the format should be {#NameofCustomField: Value}.
3. How to Update Existing Cards via Email?
Please note that only registered Businessmap users can update cards via email. More specifically:
- Only emails sent from internal users to [subdomain]_notifications@kanbanize.com or other integrated emails can update cards (e.g. change the card priority or deadline).
- External users can create new cards or add comments to existing cards by emailing integrated addresses, but they cannot update card details.
- For example, if a customer emails your integrated address with a question, it will create a new card on the default board with the email body as the card description. If you reply from the card and the customer responds to your email, their reply will be added as a comment to the existing card.
If you want to update a particular card via email, you need to specify its Card ID in the subject.
For example:
Example 1. {boardname} This is title
Example 2. {boardname}{123} This is title
The subject from Example 1 will trigger the creation of a new card.
The subject from Example 2 will trigger the update of a card with id 123.
When updating cards via email, you should use the same format as described above.
For example:
Subject: {Recruitment}{1758} Create an Assessment Report
Body: {#owner: Teo #workflowname: Reporting #lane: Default Swimlane #column: Requested #priority: critical #color: AF0020}
These properties in the email body will change the card's color and priority. The email will also be visualized as a comment inside the card:
Note that cards cannot be moved from one workflow to another via email, so the workflowname parameter would not work for updating existing cards.
This is the complete list of properties that can be used when updating cards via email:
- column – the name of the column where a card is to be moved. If you have columns with the same names, you need to specify the complete path: Column.SubColumn.Subcolumn2. If there are no subcolumns, the path should read Column.Column.
- lane - the name of the lane where a card is to be moved.
- color – Choose a color for the new card by specifying the hex code of the color without the # sign.
- priority – Define the card's priority - it can be set to low, average, high, or critical.
- size – Specify the size of the card in accordance with the board's size type setting.
- owner – Set an owner on the card - must be a valid username of an active user in the instance.
- deadline – Deadline in any of the following formats: 2012-05-05, now, 10 September 2012, -1 day, -1 week 2 days, last Monday
- tags – Set a tag on the newly created card.
- external link or extlink – Set an external link value for the card. Note that this is a custom field that needs to be available on the board where the card is to be created.
- comment – Adds a comment to the card. There could be multiple comments.
- subtask – Adds a subtask or multiple subtasks. If you add @username, the subtask will be assigned to that person. For example, #subtask: This is subtask @username2
- watcher – Set a watcher for the card, using either user name (#watcher: john) or user's ID (#watcher: 234). Note: You are able to set a watcher or add to already existing one but can not remove a watcher, using this functionality
- reason – Reason to exceed a limit.
- custom field – Set a custom field on the card - the format should be {#NameofCustomField: Value}.