From ac86c3100a1030026024c33c1cf02ec79f08ff51 Mon Sep 17 00:00:00 2001 From: Frederic Guillot Date: Sun, 19 Apr 2015 16:01:41 -0400 Subject: Add Mailgun integration (incoming emails) --- README.markdown | 1 + app/Controller/Webhook.php | 16 ++++++- app/Integration/MailgunWebhook.php | 82 +++++++++++++++++++++++++++++++++ app/Locale/da_DK/translations.php | 2 + app/Locale/de_DE/translations.php | 2 + app/Locale/es_ES/translations.php | 2 + app/Locale/fi_FI/translations.php | 2 + app/Locale/fr_FR/translations.php | 2 + app/Locale/hu_HU/translations.php | 2 + app/Locale/it_IT/translations.php | 2 + app/Locale/ja_JP/translations.php | 2 + app/Locale/nl_NL/translations.php | 2 + app/Locale/pl_PL/translations.php | 2 + app/Locale/pt_BR/translations.php | 2 + app/Locale/ru_RU/translations.php | 2 + app/Locale/sr_Latn_RS/translations.php | 2 + app/Locale/sv_SE/translations.php | 2 + app/Locale/th_TH/translations.php | 2 + app/Locale/tr_TR/translations.php | 2 + app/Locale/zh_CN/translations.php | 2 + app/Model/Project.php | 4 ++ app/ServiceProvider/ClassProvider.php | 1 + app/Template/config/integrations.php | 6 +++ assets/img/mailgun-icon.png | Bin 0 -> 632 bytes docs/mailgun.markdown | 61 ++++++++++++++++++++++++ docs/postmark.markdown | 2 +- tests/units/MailgunWebhookTest.php | 51 ++++++++++++++++++++ 27 files changed, 255 insertions(+), 3 deletions(-) create mode 100644 app/Integration/MailgunWebhook.php create mode 100644 assets/img/mailgun-icon.png create mode 100644 docs/mailgun.markdown create mode 100644 tests/units/MailgunWebhookTest.php diff --git a/README.markdown b/README.markdown index 4c4eda67..e2f137ca 100644 --- a/README.markdown +++ b/README.markdown @@ -107,6 +107,7 @@ Documentation - [Github webhooks](docs/github-webhooks.markdown) - [Gitlab webhooks](docs/gitlab-webhooks.markdown) - [Hipchat](docs/hipchat.markdown) +- [Mailgun](docs/mailgun.markdown) - [Slack](docs/slack.markdown) - [Postmark](docs/postmark.markdown) diff --git a/app/Controller/Webhook.php b/app/Controller/Webhook.php index afa0543a..06bfcd4e 100644 --- a/app/Controller/Webhook.php +++ b/app/Controller/Webhook.php @@ -112,8 +112,20 @@ class Webhook extends Base $this->response->text('Not Authorized', 401); } - $result = $this->postmarkWebhook->parsePayload($this->request->getJson() ?: array()); + echo $this->postmarkWebhook->parsePayload($this->request->getJson() ?: array()) ? 'PARSED' : 'IGNORED'; + } - echo $result ? 'PARSED' : 'IGNORED'; + /** + * Handle Mailgun webhooks + * + * @access public + */ + public function mailgun() + { + if ($this->config->get('webhook_token') !== $this->request->getStringParam('token')) { + $this->response->text('Not Authorized', 401); + } + + echo $this->mailgunWebhook->parsePayload($_POST) ? 'PARSED' : 'IGNORED'; } } diff --git a/app/Integration/MailgunWebhook.php b/app/Integration/MailgunWebhook.php new file mode 100644 index 00000000..17338faa --- /dev/null +++ b/app/Integration/MailgunWebhook.php @@ -0,0 +1,82 @@ +user->getByEmail($payload['sender']); + + if (empty($user)) { + $this->container['logger']->debug('MailgunWebhook: ignored => user not found'); + return false; + } + + // The project must have a short name + $project = $this->project->getByIdentifier($this->getMailboxHash($payload['recipient'])); + + if (empty($project)) { + $this->container['logger']->debug('MailgunWebhook: ignored => project not found'); + return false; + } + + // The user must be member of the project + if (! $this->projectPermission->isMember($project['id'], $user['id'])) { + $this->container['logger']->debug('MailgunWebhook: ignored => user is not member of the project'); + return false; + } + + // Get the Markdown contents + if (empty($payload['stripped-html'])) { + $description = $payload['stripped-text']; + } + else { + $markdown = new HTML_To_Markdown($payload['stripped-html'], array('strip_tags' => true)); + $description = $markdown->output(); + } + + // Finally, we create the task + return (bool) $this->taskCreation->create(array( + 'project_id' => $project['id'], + 'title' => $payload['subject'], + 'description' => $description, + 'creator_id' => $user['id'], + )); + } + + /** + * Get the project identifier + * + * @access public + * @param string $email + * @return string + */ + public function getMailboxHash($email) + { + list($local_part,) = explode('@', $email); + list(,$identifier) = explode('+', $local_part); + + return $identifier; + } +} diff --git a/app/Locale/da_DK/translations.php b/app/Locale/da_DK/translations.php index f021ea34..cc380929 100644 --- a/app/Locale/da_DK/translations.php +++ b/app/Locale/da_DK/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/de_DE/translations.php b/app/Locale/de_DE/translations.php index f58e4630..20d45977 100644 --- a/app/Locale/de_DE/translations.php +++ b/app/Locale/de_DE/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/es_ES/translations.php b/app/Locale/es_ES/translations.php index 3160e6f6..f1d344be 100644 --- a/app/Locale/es_ES/translations.php +++ b/app/Locale/es_ES/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/fi_FI/translations.php b/app/Locale/fi_FI/translations.php index 934f90f4..728a5746 100644 --- a/app/Locale/fi_FI/translations.php +++ b/app/Locale/fi_FI/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/fr_FR/translations.php b/app/Locale/fr_FR/translations.php index cdb9045b..54370f3a 100644 --- a/app/Locale/fr_FR/translations.php +++ b/app/Locale/fr_FR/translations.php @@ -864,4 +864,6 @@ return array( 'Identifier' => 'Identificateur', 'Postmark (incoming emails)' => 'Postmark (emails entrants)', 'Help on Postmark integration' => 'Aide sur l\'intégration avec Postmark', + 'Mailgun (incoming emails)' => 'Mailgun (emails entrants)', + 'Help on Mailgun integration' => 'Aide sur l\'intégration avec Mailgun', ); diff --git a/app/Locale/hu_HU/translations.php b/app/Locale/hu_HU/translations.php index 38bed1a2..feca5d32 100644 --- a/app/Locale/hu_HU/translations.php +++ b/app/Locale/hu_HU/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/it_IT/translations.php b/app/Locale/it_IT/translations.php index 59f057b3..8601af4f 100644 --- a/app/Locale/it_IT/translations.php +++ b/app/Locale/it_IT/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/ja_JP/translations.php b/app/Locale/ja_JP/translations.php index 9fa0a723..3a08da17 100644 --- a/app/Locale/ja_JP/translations.php +++ b/app/Locale/ja_JP/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/nl_NL/translations.php b/app/Locale/nl_NL/translations.php index 5f57937c..4a53bf48 100644 --- a/app/Locale/nl_NL/translations.php +++ b/app/Locale/nl_NL/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/pl_PL/translations.php b/app/Locale/pl_PL/translations.php index 42b2865e..519fb32b 100644 --- a/app/Locale/pl_PL/translations.php +++ b/app/Locale/pl_PL/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/pt_BR/translations.php b/app/Locale/pt_BR/translations.php index 4dd237ec..953f3a59 100644 --- a/app/Locale/pt_BR/translations.php +++ b/app/Locale/pt_BR/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/ru_RU/translations.php b/app/Locale/ru_RU/translations.php index e3039db9..dee35d70 100644 --- a/app/Locale/ru_RU/translations.php +++ b/app/Locale/ru_RU/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/sr_Latn_RS/translations.php b/app/Locale/sr_Latn_RS/translations.php index 6e4a8228..c4bab8cb 100644 --- a/app/Locale/sr_Latn_RS/translations.php +++ b/app/Locale/sr_Latn_RS/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/sv_SE/translations.php b/app/Locale/sv_SE/translations.php index abdb2b70..22286c36 100644 --- a/app/Locale/sv_SE/translations.php +++ b/app/Locale/sv_SE/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/th_TH/translations.php b/app/Locale/th_TH/translations.php index b6c140d6..c8e253b6 100644 --- a/app/Locale/th_TH/translations.php +++ b/app/Locale/th_TH/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/tr_TR/translations.php b/app/Locale/tr_TR/translations.php index 7457e0b1..5fb403e8 100644 --- a/app/Locale/tr_TR/translations.php +++ b/app/Locale/tr_TR/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Locale/zh_CN/translations.php b/app/Locale/zh_CN/translations.php index 63570ca2..7470bae1 100644 --- a/app/Locale/zh_CN/translations.php +++ b/app/Locale/zh_CN/translations.php @@ -862,4 +862,6 @@ return array( // 'Identifier' => '', // 'Postmark (incoming emails)' => '', // 'Help on Postmark integration' => '', + // 'Mailgun (incoming emails)' => '', + // 'Help on Mailgun integration' => '', ); diff --git a/app/Model/Project.php b/app/Model/Project.php index 231d57e7..158de295 100644 --- a/app/Model/Project.php +++ b/app/Model/Project.php @@ -68,6 +68,10 @@ class Project extends Base */ public function getByIdentifier($identifier) { + if (empty($identifier)) { + return false; + } + return $this->db->table(self::TABLE)->eq('identifier', strtoupper($identifier))->findOne(); } diff --git a/app/ServiceProvider/ClassProvider.php b/app/ServiceProvider/ClassProvider.php index 0c02058e..de9de546 100644 --- a/app/ServiceProvider/ClassProvider.php +++ b/app/ServiceProvider/ClassProvider.php @@ -77,6 +77,7 @@ class ClassProvider implements ServiceProviderInterface 'GithubWebhook', 'BitbucketWebhook', 'Hipchat', + 'MailgunWebhook', 'SlackWebhook', 'PostmarkWebhook', ) diff --git a/app/Template/config/integrations.php b/app/Template/config/integrations.php index b7dab2b4..a012b566 100644 --- a/app/Template/config/integrations.php +++ b/app/Template/config/integrations.php @@ -6,6 +6,12 @@ formCsrf() ?> +

 

+
+
+

+
+

 


diff --git a/assets/img/mailgun-icon.png b/assets/img/mailgun-icon.png new file mode 100644 index 00000000..41bb2783 Binary files /dev/null and b/assets/img/mailgun-icon.png differ diff --git a/docs/mailgun.markdown b/docs/mailgun.markdown new file mode 100644 index 00000000..a1dbe41b --- /dev/null +++ b/docs/mailgun.markdown @@ -0,0 +1,61 @@ +Mailgun +======= + +You can use the service [Mailgun](http://www.mailgun.com/) to create tasks directly by email. + +This integration works with the inbound email service of Mailgun (routes). +Kanboard use a webhook to handle incoming emails. + +Incoming emails workflow +------------------------ + +1. You send an email to a specific address, by example **something+myproject@inbound.mydomain.tld** +2. Your email is forwarded to Mailgun SMTP servers +3. Mailgun call the Kanboard webhook with the email in JSON format +4. Kanboard parse the received email and create the task to the right project + +Note: New tasks are automatically created in the first column. + +Email format +------------ + +- The local part of the email address must use the plus separator, by example **kanboard+project123** +- The string defined after the plus sign must match a project identifier, by example **project123** is the identifier of the project **Project 123** +- The email subject becomes the task title +- The email body becomes the task description (Markdown format) + +Incoming emails can be written in text or HTML formats. +**Kanboard is able to convert simple HTML emails to Markdown**. + +Security and requirements +------------------------- + +- The Kanboard webhook is protected by a random token +- The sender email address must match a Kanboard user +- The Kanboard project must have a unique identifier, by example **MYPROJECT** +- The Kanboard user must be member of the project + +Mailgun configuration +--------------------- + +Create a new route in the web interface or via the API ([official documentation](https://documentation.mailgun.com/user_manual.html#routes)), here an example: + +``` +match_recipient("^kanboard\+(.*)@mydomain.tld$") +forward("https://mykanboard/?controller=webhook&action=mailgun&token=mytoken") +``` + +The Kanboard webhook url is displayed in **Settings > Integrations > Mailgun** + +Kanboard configuration +---------------------- + +1. Be sure that your users have an email address in their profiles +2. Assign a project identifier to the desired projects: **Project settings > Edit** +3. Try to send an email to your project + +Troubleshootings +---------------- + +- Test if your route match in the console +- Double-check requirements mentioned above diff --git a/docs/postmark.markdown b/docs/postmark.markdown index 64beeb68..681ec5a2 100644 --- a/docs/postmark.markdown +++ b/docs/postmark.markdown @@ -21,7 +21,7 @@ Email format - The local part of the email address must use the plus separator, by example **kanboard+project123** - The string defined after the plus sign must match a project identifier, by example **project123** is the identifier of the project **Project 123** -- The email subject becomes the task subject +- The email subject becomes the task title - The email body becomes the task description (Markdown format) Incoming emails can be written in text or HTML formats. diff --git a/tests/units/MailgunWebhookTest.php b/tests/units/MailgunWebhookTest.php new file mode 100644 index 00000000..c2745180 --- /dev/null +++ b/tests/units/MailgunWebhookTest.php @@ -0,0 +1,51 @@ +container); + $p = new Project($this->container); + $pp = new ProjectPermission($this->container); + $u = new User($this->container); + $tc = new TaskCreation($this->container); + $tf = new TaskFinder($this->container); + + $this->assertEquals(2, $u->create(array('name' => 'me', 'email' => 'me@localhost'))); + + $this->assertEquals(1, $p->create(array('name' => 'test1'))); + $this->assertEquals(2, $p->create(array('name' => 'test2', 'identifier' => 'TEST1'))); + + // Empty payload + $this->assertFalse($w->parsePayload(array())); + + // Unknown user + $this->assertFalse($w->parsePayload(array('sender' => 'a@b.c', 'subject' => 'Email task', 'recipient' => 'foobar', 'stripped-text' => 'boo'))); + + // Project not found + $this->assertFalse($w->parsePayload(array('sender' => 'me@localhost', 'subject' => 'Email task', 'recipient' => 'foo+test@localhost', 'stripped-text' => 'boo'))); + + // User is not member + $this->assertFalse($w->parsePayload(array('sender' => 'me@localhost', 'subject' => 'Email task', 'recipient' => 'foo+test1@localhost', 'stripped-text' => 'boo'))); + $this->assertTrue($pp->addMember(2, 2)); + + // The task must be created + $this->assertTrue($w->parsePayload(array('sender' => 'me@localhost', 'subject' => 'Email task', 'recipient' => 'foo+test1@localhost', 'stripped-text' => 'boo'))); + + $task = $tf->getById(1); + $this->assertNotEmpty($task); + $this->assertEquals(2, $task['project_id']); + $this->assertEquals('Email task', $task['title']); + $this->assertEquals('boo', $task['description']); + $this->assertEquals(2, $task['creator_id']); + } +} -- cgit v1.2.3