====== REST API ======

---- plugin ----
description: Rest API for phpList
author     : phplist  
email      : info@phplist.com 
type       : 
compatible : 3.2.3 and later
depends    : 
conflicts  : 
similar    : 
tags       : api, rest

downloadurl: https://github.com/phpList/phplist-plugin-restapi/archive/master.zip
bugtracker : http://github.com/phpList/phplist-plugin-restapi/issues
sourcerepo : http://github.com/phpList/phplist-plugin-restapi/

----

===== Purpose =====

//Please see the newer phpList REST API which is included by default in phpList 3.4.0+//

It provides a REST API interface to phpList.

This is the continuation of the original REST API plugin by Andreas Ek

If you use this plugin, please sign up to the [[http://announce.phplist.org/?p=subscribe&id=1|phpList RestAPI list]] so that you can be informed of changes.


**IMPORTANT**: If you have used the API previous to November 2015, you will need to be careful to upgrade to the latest version. A lot has changed in the API, and if you make calls on the old API, they are likely to fail.

The previous version is available on https://github.com/phpList/phplist-plugin-restapi/archive/stable.zip

===== Installation =====

Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.


Once the plugin is installed, two plugins will list in the "Manage Plugins" page.

{{:plugin:restapi-plugins.png?nolink&700|}}


The current plugin is the one called **restapi** and you need to enable it on to use it.

The other plugin provides a set of tests.
===== Examples/Usage =====

The plugin is CI tested on https://travis-ci.org/phpList/phplist-plugin-restapi

[[https://github.com/michield/phplist-plugin-restapi/blob/stable/tests/phpunit/restapi.php|The phpUnit tests]] give examples of how to use the API

Further examples in PHP, and an example Client class, can be found at https://github.com/michield/phplist-restapi-client. Please fork and update the client.

===== Configuration =====

The plugin will add the following entries to the Settings page of phpList

{{:plugin:restapi-settings.png}}


  - **Maximum number of RESTAPI requests per minute** - will restrict the use of the API
  - **Require SSL on Rest API calls** - will enforce the URL to be on SSL. This only works if your phpList installation can be accessed via SSL
  - **IP Address that is allowed to access the API** - if you only access the phpList system from one IP address, you can use this to prevent unauthorised access attempts
  - **Require the secret code for Rest API calls** - Set this to YES to require the API calls to include the secret (//Secret for remote processing//). You will need to update your client class to include the secret.


===== Development =====


The current state of the plugin allows for simple calls to manipulate lists, subscribers, campaigns and templates.


=== Change Log ===

  * **2015/11/19** Version 3, **Major rewrite, not backwards compatible.** 
  * **2014/05/30** Initial release

=== Known Bugs and Issues ===

  - The API cannot handle Subscriber Attributes at the moment
  - Certain actions in the API need to be passed through other plugins