Skip to main content

API and integrations

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 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 repository for details.

Example API clients

Demo implementations of the API in various languages can be found in the dedicated repository.

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.

Back to top