[CRM-5998]

.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+.buildinfo
+.idea
+
+*.swp
+*.swo
+

CNAME

@@ -0,0 +1 @@
+api.myemma.com

README.md

@@ -1,4 +1,4 @@
 emma-api-documentation
 ======================
 
-Comprehensive documentation on Emma's public API can be found on the 'gh-pages' branch of this repository or at http://api.myemma.com/.
+Comprehensive documentation on Emma's public API can be found on the 'gh-pages' branch of this repository or at https://api.myemma.com/.

_sources/api/external/fields.txt

@@ -0,0 +1,12 @@
+Fields
+======
+
+These endpoints let you create, edit, update and delete all of the custom 
+fields in your account. Of particular interest is the 
+``/#account_id/fields/#field_id/clear`` endpoint which lets you clear out 
+all the data in a single field for all members in your account. This makes 
+it easy to re-initialize a dataset if you're looking to correct an import 
+error or syncing issue.
+
+.. autoemma:: audience.api.controllers.fields:FieldController
+

_sources/api/external/groups.txt

@@ -0,0 +1,12 @@
+Groups
+======
+
+With these endpoints, you can manage all aspects of the groups in 
+your account. In addition to various CRUD methods, you can also 
+use these endpoints to manage the members of your groups. You'll 
+want to use these methods if you're managing group membership for 
+more than one member at a time. For dealing with single members, 
+there are better methods in the ``members`` endpoints.
+
+.. autoemma:: audience.api.controllers.groups:MemberGroupController
+

_sources/api/external/mailings.txt

@@ -0,0 +1,9 @@
+Mailings
+========
+
+With these endpoints, you can get information about your mailings including 
+their HTML contents. You can retrieve the members to whom the mailing was sent. 
+You can also pause mailings and cancel mailings that are pending or paused.
+
+.. autoemma:: audience.api.controllers.mailings:MailingController
+

_sources/api/external/members.txt

@@ -0,0 +1,19 @@
+Members
+=======
+
+In addition to the various CRUD endpoints here related to members, 
+you can also change the status of members, including opting them out. 
+
+You'll notice that there are calls related to individual members, but 
+we also provide quite a few calls to deal with bulk updates of members. 
+Please try to use these whenever possible as opposed to looping through 
+a list of members and calling the individual member calls. 
+
+Where this is especially important is when adding new members. To do a bulk 
+import, you'll POST to the ``/#account_id/members`` endpoint. In return, 
+you'll receive an import ID. You can use this ID to check the status and 
+results of your import. Imports are generally pretty fast, but the time 
+to completion can vary with greater system usage.
+
+.. autoemma:: audience.api.controllers.members:MemberController
+

_sources/api/external/response.txt

@@ -0,0 +1,11 @@
+Response
+========
+
+We know that you want to do some fancy pivot tables with your response 
+data, so we've provided quite a few endpoints here to give you access 
+to that response data. You can get overview numbers for all of your mailings 
+and also drill down into finding out the actual members who opened a particular 
+mailing.
+
+.. autoemma:: audience.api.controllers.response:ResponseController
+

_sources/api/external/searches.txt

@@ -0,0 +1,9 @@
+Searches
+========
+
+These endpoints allow you to create, edit, and delete searches. You can also 
+retrieve the members matching any search created in your account. You can 
+:doc:`get more details on how to construct searches <../../member_search>`.
+
+.. autoemma:: audience.api.controllers.searches:SearchController
+

_sources/api/external/triggers.txt

@@ -0,0 +1,8 @@
+Triggers
+========
+
+These endpoints provide CRUD operations for our trigger system. Creating a 
+trigger is probably the most widely used of these operations.
+
+.. autoemma:: audience.api.controllers.triggers:TriggerController
+

_sources/api/external/webhooks.txt

@@ -0,0 +1,10 @@
+Webhooks
+========
+
+You can manage your webhooks with these endpoints. Of particular interest 
+might be the ``GET /#account_id/webhooks/events`` endpoint which lets you 
+know which events our system can send out webhooks for. You can :doc:`get more 
+info about how our webhooks work <../../webhooks>`.
+
+.. autoemma:: audience.api.controllers.webhooks:WebhookController
+

_sources/index.txt

@@ -0,0 +1,182 @@
+Emma API
+========
+
+A Word To The Wise...
+---------------------
+
+Use the documentation here to set up and troubleshoot your API calls. We don't offer one-on-one support
+for Emma's public API, but our system is monitored around the clock. If there's ever a dropped connection
+or outage, we'll notify users on our `status page <https://myemma.com/status>`_.
+
+Overview
+--------
+
+Emma's platform is accessible through our public API.  The API provides access
+to the following areas:
+
+* Managing member lists
+    * importing, editing, deleting
+    * organizing members into groups
+    * searching for members
+* Mailings
+    * viewing past mailings
+    * controlling the status of pending mailings
+* Retrieving response
+    * Access mailing response information by mailing, member of time period
+    * Access response at summary and detail levels
+
+API Wrappers
+------------
+
+Emma's wrappers make it easy to connect to our API in the programming language you're working in. Just select your language to integrate with Emma without having to study all the ins and outs of our API first.
+
+This collection is young, but growing, and includes wrappers commissioned by Emma, as well as those built by members of our community. Unless otherwise noted, all wrappers provide full coverage of our current API. If you see something that needs to be fixed or improved, please don't hesitate to fork the repo and submit a pull request. And if you've built a wrapper that you would like listed here, `let us know!  <mailto:[email protected]>`_
+
+**PHP**
+    `EmmaPHP <https://github.com/myemma/EmmaPHP>`_ : Commissioned by Emma and built by Nashville developer `Dennis Monsewicz <https://github.com/dennismonsewicz>`_.
+
+    `OhMyEmma <https://github.com/jwoodcock/OhMyEmma>`_: Built by Nashville developer `Jacques Woodcock <https://github.com/jwoodcock>`_.
+
+    `Emma <https://github.com/markroland/emma>`_: Built by Nashville-based `Abenity, Inc <http://www.abenity.com/>`_.
+
+**Python**
+    `EmmaPython <https://github.com/myemma/EmmaPython>`_: Built by Emma's own `Doug Hurst <https://github.com/dalanhurst>`_.
+
+**Ruby**
+    `EmmaRuby <https://github.com/myemma/EmmaRuby>`_: Commissioned by Emma and built by Nashville developer `Dennis Monsewicz <https://github.com/dennismonsewicz>`_.
+
+**Objective-C**
+    `EmmaSDK <https://github.com/myemma/EmmaSDK>`_: Commissioned by Emma and built by Portland developer `Benjamin Van Der Veen <https://github.com/bvanderveen>`_.
+
+Quickstart
+----------
+
+Let's start by building some PHP code that will add a member to our audience.
+
+First, you'll want to figure out how to authenticate. All calls require HTTP
+Basic Auth authentication. Inside your Emma account, in the "Account Settings"
+section, you'll find your API keys. There's a public key and a private key and
+an account ID. It should look like this.
+
+.. image:: images/api_keys.jpg
+
+So, let's add these authentication bits to our code.
+
+.. code-block:: php
+
+  // Authentication Variables
+  $account_id = "xxx";
+  $public_api_key = "xxx";
+  $private_api_key = "xxx";
+
+Then, we'll want to capture the POSTed form variables from the request.
+
+.. code-block:: php
+
+  // Form variable(s)
+  $email = $_POST['email'];
+  $first_name = $_POST['first_name'];
+  $last_name = $_POST['last_name'];
+  $groups = array(123456, 654321);
+
+  // Member data other than email should be passed in an array called "fields"
+  $member_data = array(
+    "email" => $email,
+    "fields" => array(
+      "first_name" => $first_name,
+      "last_name" => $last_name
+    ),
+    "group_ids" => $groups
+  );
+
+Please note that the ``group_ids`` to which the member will be added are passed
+as an array of integers. Of course, you'll want to make sure you sanitize any of
+these form inputs to protect your application.
+
+Let's set the URL for the API call. The endpoint for all of our API calls is
+https://api.e2ma.net/. In this case, we're using the endpoint that
+corresponds to adding a single member. There's a separate call for adding bulk
+members.
+
+.. code-block:: php
+
+  // Set URL
+  $url = "https://api.e2ma.net/".$account_id."/members/add";
+
+Next, we'll do a little dance with cURL that I'm sure is familiar. I'll
+explain some particulars below the code block.
+
+.. code-block:: php
+  :emphasize-lines: 3,6,7
+
+  // setup and execute the cURL command
+  $ch = curl_init();
+  curl_setopt($ch, CURLOPT_USERPWD, $public_api_key . ":" . $private_api_key);
+  curl_setopt($ch, CURLOPT_URL, $url);
+  curl_setopt($ch, CURLOPT_POST, count($member_data));
+  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($member_data));
+  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-type: application/json'));
+  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
+  $head = curl_exec($ch);
+  $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+  curl_close($ch);
+
+On line 3 is where we use the public/private keys to authenticate our call.
+On lines 6-7, we force the API call to make its request in JSON and expect
+JSON in return.
+
+At this point, the API call has been made.We might want to inspect the
+result to see what happened. The API returns true HTTP response codes which
+you can examine to determine a request's disposition.
+
+.. code-block:: php
+
+  //execute post
+  if($http_code > 200) {
+    $app_message = "Error sending subscription request";
+  } else {
+    $app_message = "Success!";
+  }
+
+  echo $app_message;
+
+You can :doc:`see the complete PHP script here <php_signup_example>`.
+Additionally, there's a PHP example to :doc:`get members using their email
+address <php_get_member_example>`.
+
+To extend this example further, one could make the API call associate the
+new member with a particular signup form. As written above, the member would
+be added to the audience but would not appear in the "recent activity" type
+searches or really any searches related to signups. We are working on a
+cleaner way to handle this signup form issue in the future.
+
+
+API calls by category
+---------------------
+
+The API calls are organized by their main entity type in the following
+sections.  Each call includes sample request & response data.
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    api/external/*
+
+Additional Documentation
+------------------------
+
+.. toctree::
+    :maxdepth: 2
+
+    pagination
+    placeholders
+    member_search
+    webhooks
+
+.. toctree::
+    :hidden:
+
+    php_signup_example
+    php_get_member_example