This page concerns phpList self-hosted users only. If you have a registered account at the phpList Hosted service, please contact hosted@phpList.com.
phpList is a stand-alone solution which can also be integrated into other systems, workflows, and applications. This can be as simple as automatically adding a sign-up form for a newsletter list to your Wordpress blog, or as complex as using phpList as one of many components in a larger automated enterprise resource planning system. ## Application Programming Interface (API) phpList 3.4.0 and later includes a REST API which, when enabled, allows other software systems to interact with it in a variety of ways, such as managing subscribers, lists, and campaigns. ### System requirements The REST API has different server requirements than phpList 3 — it may not be compatible with your environment even if you are already using phpList 3 successfully. The most significant difference is the requirement of PHP 7. Apache users must also have support for `.htaccess` files and ` mod_rewrite` enabled in order to use the API securely. For the full list of requirements please see the [System Requirements](https://github.com/phpList/base-distribution#phplist-4-base-distribution) of phpList 4. ### Enable the API - Open the following file with a text editor: `public_html/lists/base/config/config_modules.yml` - Change `false` to `true` on the following line: `{ view_response_listener: { enabled: false } }` - Delete this folder entirely: `public_html/lists/base/var/cache` ### Access the API By default the base URL for API requests is `http://my-website.com/lists/api/v2/`. So, to authenticate a new API session you could use the following URL: `http://my-website.com/lists/api/v2/sessions`. This access URL can be changed by editing your webserver configuration. ### Test the API To check if the API is enabled and working properly, you can try authenticating a new session from a Linux or Mac terminal using the `curl` command-line utility. Substitute the example phpList installation URL, and phpList admin username and password, in the following command, and copy and paste it into your terminal: ``` curl --request POST --url http://my-website.com/lists/api/v2/sessions --header 'Content-Type: application/json'--data '{"login_name": "admin","password": "phplist"}' ``` The output should be similar to the following, with a different expiry date, key, and id: `{"expiry":"2019-03-31T18:16:42+00:00","key":"24244871cf45aa2f1c0dbddf82b9912b","id":6}` If instead, you see a message in HTML stating '403 Forbidden', then you should check your webserver's permission configuration. Non-superuser administrators cannot authenticate via the REST API. Given valid login data, this will generate a login token that will be valid for 1 hour. The login token then can be passed as basic auth password for requests that require authentication. ### Examples of API clients/ implementations To demonstrate how to use the API some example clients are available in different programming languages. See the [REST API Client Examples](https://github.com/phpList/RestAPIclientSimpleExample) repository for details. ### Example API clients Demo implementations of the API in various languages can be found in the dedicated [repository](https://github.com/phpList/RestAPIclientSimpleExample). ### Enable API logging The following steps will enable logging of API requests and errors: - Edit the following file: `public_html/lists/base/vendor/phplist/core/config/config_prod.yml` - Remove the pound (`#`) from the beginning of every line from line 4 onwards to uncomment them ### Supported API actions For complete documentation of all supported REST API actions please see the [API Blueprint](https://github.com/phpList/rest-api/blob/master/docs/Api/RestApi.apib).