Content:
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 Kanbanize email integration feature.
All you need to do is send an email to an email-integrated user in Kanbanize.
Such a recipient can be:
- A Kanbanize email address that is configured as an email integration user in your Kanbanize 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 Kanbanize 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 Kanbanize 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 Kanbanize 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?
In order 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: {Board A} Create a KPI Report
Body: {#owner: John #column: Requested}
This email will create a new card on the board called “Board A” with a card title “Create a KPI Report”. The card will be assigned to John 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}
Important: The email body properties (e.g. title, description, owner, etc.) are case-sensitive and have to be specified in lowercase. In case the properties are specified as Title, Description, or Owner, the values on those fields will be ignored.
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 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. Note that if the template contains linked cards, they will not be applied.
- 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 cards can be updated only by senders that are registered members of the Kanbanize instance. If an external user attempts to update a card via email, the properties from their email body will be ignored, and any other text in the body will be added as a comment on the 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:
{#owner: John #color: FF00FF #column: Requested #lane: Default}
These properties in the email body will change the card color and owner and will move the card to the defined position.
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.
- 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.
- template – Apply a template on the card. Note that if the template contains linked cards, they will not be applied.
- custom field – Set a custom field on the card - the format should be {#NameofCustomField: Value}.