Merge pull request #47 from bakura10/mailgun-routes

Add support for routes

CHANGELOG.md

@@ -6,6 +6,8 @@
 - Allow up to one BCC address for Mandrill
 - Add following options to Mandrill messages: return_path_domain, subaccount
 - Updated Mandrill doc
+- Add support for Mailgun routes
+- Updated Mailgun doc
 
 ## 1.0.1
 

README.md

@@ -23,7 +23,7 @@ Here are the currently supported services:
 * [AlphaMail](http://www.amail.io) (complete)
 * [Amazon SES](http://aws.amazon.com/ses) (nearly complete, [attachments are missing](https://github.com/juriansluiman/SlmMail/issues/44))
 * [Elastic Email](http://elasticemail.com) (complete)
-* [Mailgun](http://www.mailgun.com) (nearly complete - advanced features like Routes are not supported -)
+* [Mailgun](http://www.mailgun.com) (complete)
 * [Mandrill](http://mandrill.com) (complete)
 * [Postmark](https://postmarkapp.com) (complete)
 * [Postage](http://postageapp.com) (complete)

docs/Mailgun.md

@@ -121,6 +121,15 @@ Spam functions:
 * `addSpamComplaint($address)`: add an address to the complaints table ([docs](http://documentation.mailgun.com/api-complaints.html))
 * `deleteSpamComplaint($address)`: delete an address from spam complaint ([docs](http://documentation.mailgun.com/api-complaints.html))
 
+Route functions:
+
+* `addRoute($description, $expression, $actions, $priority = 0)`: add a new route ([docs](http://documentation.mailgun.com/api-routes.html))
+* `deleteRoute($id)`: delete an existing route ([docs](http://documentation.mailgun.com/api-routes.html))
+* `getRoutes($limit = 100, $offset = 0)`: get routes ([docs](http://documentation.mailgun.com/api-routes.html))
+* `getRoute($id)`: get route by its identifier ([docs](http://documentation.mailgun.com/api-routes.html))
+* `updateRoute($id, $description, $expression, $actions, $priority = 0)`: update an existing route ([docs](http://documentation.mailgun.com/api-routes.html))
+
+
 Bounce functions:
 
 * `getBounces($limit = 100, $offset = 0)`: get bounces ([docs](http://documentation.mailgun.com/api-bounces.html))

src/SlmMail/Mail/Message/Mailgun.php

@@ -92,6 +92,7 @@ public function setTags(array $tags)
                 'Mailgun only allows up to %s tags', self::TAG_LIMIT
             ));
         }
+
         $this->tags = $tags;
         return $this;
     }
@@ -127,7 +128,7 @@ public function setOptions(array $options)
         foreach ($options as $key => $value) {
             if (!array_key_exists($key, $this->getValidOptions())) {
                 throw new Exception\InvalidArgumentException(sprintf(
-                    'Invalid option %s given', $key
+                    'Invalid option "%s" given', $key
                 ));
             }
         }
@@ -148,7 +149,7 @@ public function setOption($key, $value)
     {
         if (!array_key_exists($key, $this->getValidOptions())) {
             throw new Exception\InvalidArgumentException(sprintf(
-                'Invalid option %s given', $key
+                'Invalid option "%s" given', $key
             ));
         }
 

src/SlmMail/Service/MailgunService.php

@@ -87,7 +87,7 @@ public function __construct($domain, $apiKey)
 
     /**
      * {@inheritDoc}
-     * @link http://help.postageapp.com/kb/api/send_message
+     * @link http://documentation.mailgun.com/api-sending.html
      * @return string id of message (if sent correctly)
      */
     public function send(Message $message)
@@ -333,20 +333,144 @@ public function deleteBounce($address)
         return $this->parseResponse($response);
     }
 
+    /**
+     * ------------------------------------------------------------------------------------------
+     * ROUTES
+     * ------------------------------------------------------------------------------------------
+     */
+
+    /**
+     * Add a new route (expression and action must be valid according to Mailgun syntax)
+     *
+     * @link http://documentation.mailgun.com/api-routes.html
+     * @param  string       $description A description for the route
+     * @param  string       $expression  A filter expression
+     * @param  string|array $actions     A single or multiple actions
+     * @param  int          $priority    Optional priority (smaller number indicates higher priority)
+     * @return array
+     */
+    public function addRoute($description, $expression, $actions, $priority = 0)
+    {
+        $actions = (array) $actions;
+
+        $parameters = array(
+            'description' => $description,
+            'expression'  => $expression,
+            'action'      => array_reverse($actions), // For unknown reasons, Mailgun API saves
+                                                      // routes in the opposite order as you specify
+                                                      // them, hence the array_reverse
+            'priority'    => $priority
+        );
+
+        $response = $this->prepareHttpClient('/routes', $parameters, false)
+                         ->send();
+
+        return $this->parseResponse($response);
+    }
+
+    /**
+     * Delete an existing route
+     *
+     * @link @link http://documentation.mailgun.com/api-routes.html
+     * @param  string $id
+     * @return array
+     */
+    public function deleteRoute($id)
+    {
+        $response = $this->prepareHttpClient('/routes/' . $id, array(), false)
+                         ->setMethod(HttpRequest::METHOD_DELETE)
+                         ->send();
+
+        return $this->parseResponse($response);
+    }
+
+    /**
+     * Get all the routes
+     *
+     * @link http://documentation.mailgun.com/api-routes.html
+     * @param  int $limit
+     * @param  int $offset
+     * @return array
+     */
+    public function getRoutes($limit = 100, $offset = 0)
+    {
+        $parameters = array('limit' => $limit, 'skip' => $offset);
+
+        $response = $this->prepareHttpClient('/routes', array(), false)
+                         ->setMethod(HttpRequest::METHOD_GET)
+                         ->setParameterGet($this->filterParameters($parameters))
+                         ->send();
+
+        return $this->parseResponse($response);
+    }
+
+    /**
+     * Get route details
+     *
+     * @link http://documentation.mailgun.com/api-routes.html
+     * @param  string $id
+     * @return array
+     */
+    public function getRoute($id)
+    {
+        $response = $this->prepareHttpClient('/routes/' . $id, array(), false)
+                         ->setMethod(HttpRequest::METHOD_GET)
+                         ->send();
+
+        return $this->parseResponse($response);
+    }
+
+    /**
+     * Update an existing route (expression and action must be valid according to Mailgun syntax)
+     *
+     * @link http://documentation.mailgun.com/api-routes.html
+     * @param  string       $id          Identifier of the route
+     * @param  string       $description A description for the route
+     * @param  string       $expression  A filter expression
+     * @param  string|array $actions     A single or multiple actions
+     * @param  int          $priority    Optional priority (smaller number indicates higher priority)
+     * @return array
+     */
+    public function updateRoute($id, $description = '', $expression = '', $actions = array(), $priority = 0)
+    {
+        $actions = (array) $actions;
+
+        $parameters = array(
+            'description' => $description,
+            'expression'  => $expression,
+            'action'      => array_reverse($actions), // For unknown reasons, Mailgun API saves
+                                                      // routes in the opposite order as you specify
+                                                      // them, hence the array_reverse
+            'priority'    => $priority
+        );
+
+        $response = $this->prepareHttpClient('/routes/' . $id, $parameters, false)
+                         ->setMethod(HttpRequest::METHOD_PUT)
+                         ->send();
+
+        return $this->parseResponse($response);
+    }
+
     /**
      * @param string $uri
-     * @param array $parameters
+     * @param array  $parameters
+     * @param bool   $perDomain
      * @return \Zend\Http\Client
      */
-    private function prepareHttpClient($uri, array $parameters = array())
+    private function prepareHttpClient($uri, array $parameters = array(), $perDomain = true)
     {
         $client = $this->getClient()->resetParameters();
         $client->getRequest()
                ->getHeaders()
                ->addHeaderLine('Authorization', 'Basic ' . base64_encode('api:' . $this->apiKey));
 
+        if ($perDomain) {
+            $client->setUri(self::API_ENDPOINT . '/' . $this->domain . $uri);
+        } else {
+            $client->setUri(self::API_ENDPOINT . $uri);
+        }
+
         return $client->setMethod(HttpRequest::METHOD_POST)
-                      ->setUri(self::API_ENDPOINT . '/' . $this->domain . $uri)
                       ->setParameterPost($this->filterParameters($parameters));
     }