From af98ed33071fb9336110e5b93448661355538aff Mon Sep 17 00:00:00 2001
From: Tobias Nyholm <tobias.nyholm@gmail.com>
Date: Sat, 8 Apr 2017 10:45:25 +0200
Subject: [PATCH] Added documentation for the API classes (#328)

* Added documentation for the API classes

* Added more docs

* Added domain

* Typo

* Minor fixes
---
 README.md          |  11 +-
 doc/attachments.md |  47 +++++++
 doc/index.md       | 311 +++++++++++++++++++++++++++++++++++++++++++++
 doc/pagination.md  |  17 +++
 4 files changed, 383 insertions(+), 3 deletions(-)
 create mode 100644 doc/attachments.md
 create mode 100644 doc/index.md
 create mode 100644 doc/pagination.md

diff --git a/README.md b/README.md
index f714021..efd4847 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,11 @@ $mg->message()->send('example.com', [
 ]);
 ```
 
+### All usage examples
+
+You find more detailed documentation at in [/doc](doc/index.md) and on 
+[https://documentation.mailgun.com](https://documentation.mailgun.com/api_reference.html).
+
 ### Response
 
 The results of a API call is, by default, a domain object. This will make it easy
@@ -129,12 +134,12 @@ $configurator->setDebug(true);
 $mg = Mailgun::configure($configurator);
 
 # Now, compose and send your message.
-$mg->sendMessage('example.com', [
+$mg->messages()->send('example.com', [
   'from'    => 'bob@example.com', 
   'to'      => 'sally@example.com', 
   'subject' => 'The PHP SDK is awesome!', 
-  'text'    => 'It is so simple to send a message.']
-);
+  'text'    => 'It is so simple to send a message.'
+]);
 ```
 ### Additional Info
 
diff --git a/doc/attachments.md b/doc/attachments.md
new file mode 100644
index 0000000..92f5090
--- /dev/null
+++ b/doc/attachments.md
@@ -0,0 +1,47 @@
+# Attachments
+
+You may attach a file from memory or by a file path.
+
+## From file path
+
+```php
+$mg->message()->send('example.com', [
+  'from'    => 'bob@example.com', 
+  'to'      => 'sally@example.com', 
+  'subject' => 'Test file path attachments', 
+  'text'    => 'Test',
+  'attachment' => [
+    ['filePath'=>'/tmp/foo.jpg', 'filename'=>'test.jpg']
+  ]
+]);
+```
+## From memory
+
+```php
+// Some how load the file to memory
+$binaryFile = '[Binary data]';
+
+$mg->message()->send('example.com', [
+  'from'    => 'bob@example.com', 
+  'to'      => 'sally@example.com', 
+  'subject' => 'Test memory attachments', 
+  'text'    => 'Test',
+  'attachment' => [
+    ['fileContent'=>$binaryFile, 'filename'=>'test.jpg']
+  ]
+]);
+```
+
+## Inline attachments
+
+```php
+$mg->message()->send('example.com', [
+  'from'    => 'bob@example.com', 
+  'to'      => 'sally@example.com', 
+  'subject' => 'Test inline attachments', 
+  'text'    => 'Test',
+  'inline' => [
+    ['filePath'=>'/tmp/foo.jpg', 'filename'=>'test.jpg']
+  ]
+]);
+```
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 0000000..ed98f37
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,311 @@
+# API documentation
+
+This page will document the API classes and ways to properly use the API. These resources will eventually move to
+the official documentation at [https://documentation.mailgun.com](https://documentation.mailgun.com/api_reference.html).
+
+Other relevant documentation pages might be: 
+ 
+* [Attachments](attachments.md)
+* [Pagination](pagination.md)
+* [Message Builder](src/Mailgun/Messages/README.md) (Legacy code)
+* [Batch Message](src/Mailgun/Messages/README.md) (Legacy code)
+* [Opt-In Handler](src/Mailgun/Lists/README.md)  (Legacy code)
+
+## Domain API
+
+#### Get a list of all domains
+
+```php
+$mailgun->domains()->index();
+```
+
+#### Show a single domains
+
+```php
+$mailgun->domains()->show('example.com');
+```
+
+#### Create a new domain
+
+```php
+$mailgun->domains()->create('new.example.com', 'password', 'disable', '*');
+```
+
+#### Delete a domain
+
+```php
+$mailgun->domains()->delete('example.com');
+```
+
+#### Get credentials for a domain
+
+```php
+$mailgun->domains()->credentials('example.com');
+```
+
+#### Create credentials for a domain
+
+```php
+$mailgun->domains()->createCredential('example.com', 'login', 'password');
+```
+
+#### Update credentials for a domain
+
+```php
+$mailgun->domains()->updateCredential('example.com', 'login', 'password');
+```
+
+#### Delete credentials for a domain
+
+```php
+$mailgun->domains()->deleteCredential('example.com', 'login');
+```
+
+#### Get connection for a domain
+
+```php
+$mailgun->domains()->connection('example.com');
+```
+
+#### Update connection for a domain
+
+```php
+$mailgun->domains()->updateConnection('example.com', true, false);
+```
+
+## Event API
+
+#### Get all events for a domain
+```php
+$mailgun->events()->get('example.com');
+```
+
+## Message API
+
+#### Send a message
+```php
+$parameters = [
+    'from'    => 'bob@example.com', 
+    'to'      => 'sally@example.com', 
+    'subject' => 'The PHP SDK is awesome!', 
+    'text'    => 'It is so simple to send a message.'
+];
+$mailgun->messages()->send('example.com', $parameters);
+```
+
+#### Show a stored message
+
+If you got an URL to a stored message you may get the details by:
+
+```php
+$url = // ...
+$mailgun->messages()->show($url);
+```
+
+## Route API
+
+#### Show all routes
+
+```php
+$mailgun->routes()->index();
+```
+
+#### Show a routes
+
+Get a route by its ID
+
+```php
+$mailgun->routes()->show(4711);
+```
+#### Create a route
+
+```php
+$expression = "match_recipient('.*@gmail.com')";
+$actions = ["forward('alice@example.com')"];
+$description = 'Test route';
+
+$mailgun->routes()->create($expression, $actions, $description);
+```
+
+#### Update a route
+
+```php
+$expression = "match_recipient('.*@gmail.com')";
+$actions = ["forward('alice@example.com')"];
+$description = 'Test route';
+
+$mailgun->routes()->update(4711, $expression, $actions, $description);
+```
+
+#### Delete a route
+```php
+$mailgun->routes()->delete(4711);
+```
+
+## Stats API
+
+#### Get total stats for a domain
+```php
+$mailgun->stats()->total('example.com');
+```
+
+#### Get all stats for a domain
+```php
+$mailgun->stats()->all('example.com');
+```
+
+
+## Suppression API
+
+The suppression API consists of 3 parts; `Bounce`, `Complaint` and `Unsubscribe`.
+
+### Bounce API
+#### Get all bounces
+```php
+$mailgun->suppressions()->bounces()->index('example.com');
+```
+
+#### Show bounces for a specific address
+```php
+$mailgun->suppressions()->bounces()->show('example.com', 'alice@gmail.com');
+```
+
+#### Create a bounce
+```php
+$mailgun->suppressions()->bounces()->create('example.com', 'alice@gmail.com');
+```
+
+#### Delete a bounce
+```php
+$mailgun->suppressions()->bounces()->delete('example.com', 'alice@gmail.com');
+```
+
+#### Delete all bounces
+```php
+$mailgun->suppressions()->bounces()->deleteAll('example.com');
+```
+
+### Complaint API
+#### Get all complaints
+```php
+$mailgun->suppressions()->complaints->index('example.com');
+```
+
+#### Show complaints for a specific address
+```php
+$mailgun->suppressions()->complaints()->show('example.com', 'alice@gmail.com');
+```
+
+#### Create a complaint
+```php
+$mailgun->suppressions()->complaints()->create('example.com', 'alice@gmail.com');
+```
+
+#### Delete a complaint
+```php
+$mailgun->suppressions()->complaints()->delete('example.com', 'alice@gmail.com');
+```
+
+#### Delete all complaints
+```php
+$mailgun->suppressions()->complaints()->deleteAll('example.com');
+```
+
+## Unsubscribe API
+
+#### Get all unsubscriptions
+```php
+$mailgun->suppressions()->unsubscribes()->index('example.com');
+```
+
+#### Show unsubscriptions for a specific address
+```php
+$mailgun->suppressions()->unsubscribes()->show('example.com', 'alice@gmail.com');
+```
+
+#### Create an unsubscription
+```php
+$mailgun->suppressions()->unsubscribes()->create('example.com', 'alice@gmail.com');
+```
+
+#### Delete an unsubscription
+```php
+$mailgun->suppressions()->unsubscribes()->delete('example.com', 'alice@gmail.com');
+```
+
+#### Delete all unsubscriptions
+```php
+$mailgun->suppressions()->unsubscribes()->deleteAll('example.com');
+```
+
+## Tag API
+
+#### Show all tags
+```php
+$mailgun->tags()->index('example.com');
+```
+
+#### Show a single tag
+```php
+$mailgun->tags()->show('example.com', 'foo');
+```
+
+#### Update a tag
+```php
+$mailgun->tags()->update('example.com', 'foo', 'description');
+```
+
+#### Show stats for a tag
+```php
+$mailgun->tags()->stats('example.com', 'foo');
+```
+
+#### Delete a tag
+```php
+$mailgun->tags()->delete('example.com', 'foo');
+```
+
+## Webhook API
+#### Verify webhook signature
+```php
+
+$timestamp = $_POST['timestamp'];
+$token = $_POST['token'];
+$signature = $_POST['signature'];
+
+$mailgun = Maingun::create('my_api_key');
+$valid = $mailgun->webhooks()->verifyWebhookSignature($timestamp, $token, $signature);
+
+if (!$valid) {
+    // Create a 403 response
+    
+    exit();
+}
+
+// The signature is valid
+```
+
+#### Show all webhooks
+```php
+$mailgun->webhooks()->index('example.com');
+```
+
+#### Show a single webhooks
+```php
+$mailgun->webhooks()->show('example.com', 'accept');
+```
+
+#### Create a webhooks
+```php
+$mailgun->webhooks()->create('example.com', 'accept', 'https://www.exmple.com/webhook');
+```
+
+#### Update a webhooks
+```php
+$mailgun->webhooks()->update('example.com', 4711, 'https://www.exmple.com/webhook');
+```
+
+#### Delete a webhooks
+```php
+$mailgun->webhooks()->delete('example.com', 4711);
+```
diff --git a/doc/pagination.md b/doc/pagination.md
new file mode 100644
index 0000000..2fbcd5d
--- /dev/null
+++ b/doc/pagination.md
@@ -0,0 +1,17 @@
+# Pagination
+
+Some API endpoints do support pagination. 
+
+```php
+
+/** @var Mailgun\Model\Tag\IndexReponse $response */
+$reponse = $mailgun->tags()->index('example.com');
+
+// Parse through the first response
+// ...
+
+$nextResponse = $mailgun->tags()->nextPage($response);
+$previousResponse = $mailgun->tags()->previousPage($response);
+$firstResponse = $mailgun->tags()->firstPage($response);
+$lastResponse = $mailgun->tags()->lastPage($response);
+```