beenull/listmonk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Refactor and clean up API Markdown docs.

Browse source 
This has been pending for several years. Finally, managed to do with
GPT-4 "auto" cleaning language and other consistency issues.
90% GPT4, 10% manual hand-wringing.

GPT-4 prompt:
```
- Fix grammar, simplify language, and make language and terms consistent.
- Remove superfluous language, avoid unncessary "the"s etc.
- Change endpoint description in tables that list endpoints, change to terse imperative language.
- Parameter / field description in Parameter tables, don't be imperative or use active sentences. Only describe the parameter passively and tersely.
- Remove backticks from all headings and table values.
- Format markdown tables.
- Standardize "data type" columns values into number, string[], string, JSON.
- Remove the "parameter type" column from tables.
- Wrap ID parameters in URIs in braces. Eg: /lists/list_id to /lists/{list_id}
- Add a markdown line above every API path heading that begins with GET, POST, PUT, DELETE.
- Leave the lines starting with `#code-` untouched
- Do not add new sections, headings, or any new content. Only edit existing content as described above.
- Do not remove any sections or any existing content.
```
This commit is contained in:
Kailash Nadh 2023-11-10 12:19:30 +05:30
parent f8a55f84fa
commit be4be729a9
10 changed files with 609 additions and 514 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
docs/docs/content/apis/apis.md
View file

@ -44,15 +44,15 @@ All timestamp fields are in the format `2019-01-01T09:00:00.000000+05:30`. The s
### Common HTTP error codes ### Common HTTP error codes
| code |   | | Code | |
| ----- | ------------------------------------------------------------------------ | | ----- | ------------------------------------------------------------------------ |
| `400` | Missing or bad request parameters or values | | 400 | Missing or bad request parameters or values |
| `403` | Session expired or invalidate. Must relogin | | 403 | Session expired or invalidate. Must relogin |
| `404` | Request resource was not found | | 404 | Request resource was not found |
| `405` | Request method (GET, POST etc.) is not allowed on the requested endpoint | | 405 | Request method (GET, POST etc.) is not allowed on the requested endpoint |
| `410` | The requested resource is gone permanently | | 410 | The requested resource is gone permanently |
| `429` | Too many requests to the API (rate limiting) | | 429 | Too many requests to the API (rate limiting) |
| `500` | Something unexpected went wrong | | 500 | Something unexpected went wrong |
| `502` | The backend OMS is down and the API is unable to communicate with it | | 502 | The backend OMS is down and the API is unable to communicate with it |
| `503` | Service unavailable; the API is down | | 503 | Service unavailable; the API is down |
| `504` | Gateway timeout; the API is unreachable | | 504 | Gateway timeout; the API is unreachable |

216
docs/docs/content/apis/campaigns.md
View file

@ -1,20 +1,22 @@
# API / Campaigns # API / Campaigns
Method | Endpoint | Description | Method | Endpoint | Description |
---------|------------------------------------------------------------------------------|------------------------------------------------------------- |:-------|:----------------------------------------------------------------------------|:------------------------------------------|
`GET` | [/api/campaigns](#get-apicampaigns) | Gets all campaigns. | GET | [/api/campaigns](#get-apicampaigns) | Retrieve all campaigns. |
`GET` | [/api/campaigns/:`campaign_id`](#get-apicampaignscampaign_id) | Gets a single campaign. | GET | [/api/campaigns/{campaign_id}](#get-apicampaignscampaign_id) | Retrieve a specific campaign. |
`GET` | [/api/campaigns/:`campaign_id`/preview](#get-apicampaignscampaign_idpreview) | Gets the HTML preview of a campaign body. | GET | [/api/campaigns/{campaign_id}/preview](#get-apicampaignscampaign_idpreview) | Retrieve preview of a campaign. |
`GET` | [/api/campaigns/running/stats](#get-apicampaignsrunningstats) | Gets the stats of a given set of campaigns. | GET | [/api/campaigns/running/stats](#get-apicampaignsrunningstats) | Retrieve stats of specified campaigns. |
`POST` | [/api/campaigns](#post-apicampaigns) | Creates a new campaign. | POST | [/api/campaigns](#post-apicampaigns) | Create a new campaign. |
`POST` | /api/campaigns/:`campaign_id`/test | Posts campaign message to arbitrary subscribers for testing. | POST | [/api/campaigns/{campaign_id}/test](#post-apicampaignscampaign_idtest) | Test campaign with arbitrary subscribers. |
`PUT` | /api/campaigns/:`campaign_id` | Modifies a campaign. | PUT | [/api/campaigns/{campaign_id}](#put-apicampaignscampaign_id) | Update a campaign. |
`PUT` | [/api/campaigns/:`campaign_id`/status](#put-apicampaignscampaign_idstatus) | Start / pause / cancel / schedule a campaign. | PUT | [/api/campaigns/{campaign_id}/status](#put-apicampaignscampaign_idstatus) | Change status of a campaign. |
`DELETE` | [/api/campaigns/:`campaign_id`](#delete-apicampaignscampaign_id) | Deletes a campaign. | DELETE | [/api/campaigns/{campaign_id}](#delete-apicampaignscampaign_id) | Delete a campaign. |
#### ```GET``` /api/campaigns ______________________________________________________________________
Gets all campaigns. #### GET /api/campaigns
Retrieve all campaigns.
##### Example Request ##### Example Request
@ -23,18 +25,18 @@ Gets all campaigns.
``` ```
##### Parameters ##### Parameters
| Name | Type | Required/Optional | Description |
|-----------|--------|-------------------|-------------|
| `query` | string | Optional | Optional string to search a list by name. |
| `order_by`| string | Optional | Field to sort results by. Options: `name`, `status`, `created_at`, `updated_at`. |
| `order` | string | Optional | Sort order: `ASC` for ascending, `DESC` for descending. |
| `page` | number | Optional | Page number for paginated results. |
| `per_page`| number | Optional | Results to return per page. Setting this to `all` skips pagination and returns all results. |
| Name | Type | Required | Description |
|:---------|:-------|:---------|:---------------------------------------------------------------------|
| order | string | | Sorting order: ASC for ascending, DESC for descending. |
| order_by | string | | Result sorting field. Options: name, status, created_at, updated_at. |
| query | string | | SQL query expression to filter subscribers. |
| page | number | | Page number for paginated results. |
| per_page | number | | Results per page. Set as 'all' for all results. |
##### Example Response ##### Example Response
``` json ```json
{ {
"data": { "data": {
"results": [ "results": [
@ -42,7 +44,6 @@ Gets all campaigns.
"id": 1, "id": 1,
"created_at": "2020-03-14T17:36:41.29451+01:00", "created_at": "2020-03-14T17:36:41.29451+01:00",
"updated_at": "2020-03-14T17:36:41.29451+01:00", "updated_at": "2020-03-14T17:36:41.29451+01:00",
"CampaignID": 0,
"views": 0, "views": 0,
"clicks": 0, "clicks": 0,
"lists": [ "lists": [
@ -78,31 +79,32 @@ Gets all campaigns.
} }
``` ```
#### ```GET``` /api/campaigns/:`campaign_id` ______________________________________________________________________
Gets a single campaign. #### GET /api/campaigns/{campaign_id}
##### Parameters Retrieve a specific campaign.
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|-----------|-------------------|-----------------------------------------------
`campaign_id` | Path Parameter | Number | Required | The id value of the campaign you want to get.
##### Parameters
| Name | Type | Required | Description |
|:------------|:----------|:---------|:-------------|
| campaign_id | number | Yes | Campaign ID. |
##### Example Request ##### Example Request
``` shell ```shell
curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1' curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1'
``` ```
##### Example Response ##### Example Response
``` json ```json
{ {
"data": { "data": {
"id": 1, "id": 1,
"created_at": "2020-03-14T17:36:41.29451+01:00", "created_at": "2020-03-14T17:36:41.29451+01:00",
"updated_at": "2020-03-14T17:36:41.29451+01:00", "updated_at": "2020-03-14T17:36:41.29451+01:00",
"CampaignID": 0,
"views": 0, "views": 0,
"clicks": 0, "clicks": 0,
"lists": [ "lists": [
@ -132,20 +134,17 @@ curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1'
} }
``` ```
______________________________________________________________________
#### GET /api/campaigns/{campaign_id}/preview
Preview a specific campaign.
#### ```GET``` /api/campaigns/:`campaign_id`/preview ##### Parameters
Gets the html preview of a campaign body.
##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|-----------|-------------------|----------------------------------------------
`campaign_id` | Path Parameter | Number | Required | The id value of the campaign to be previewed.
| Name | Type | Required | Description |
|:------------|:----------|:---------|:------------------------|
| campaign_id | number | Yes | Campaign ID to preview. |
##### Example Request ##### Example Request
@ -155,71 +154,69 @@ curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1/previe
##### Example Response ##### Example Response
``` html ```html
<h3>Hi John!</h3> <h3>Hi John!</h3>
This is a test e-mail campaign. Your second name is Doe and you are from Bengaluru. This is a test e-mail campaign. Your second name is Doe and you are from Bengaluru.
``` ```
#### ```GET``` /api/campaigns/running/stats ______________________________________________________________________
Gets the running stat of a given set of campaigns. #### GET /api/campaigns/running/stats
Retrieve stats of specified campaigns.
##### Parameters ##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description | Name | Type | Required | Description |
------------|------------------|-----------|-------------------|----------------------------------------------------------- |:------------|:----------|:---------|:-------------------------------|
campaign_id | Query Parameters | Number | Required | The id values of the campaigns whose stat you want to get. | campaign_id | number | Yes | Campaign IDs to get stats for. |
##### Example Request ##### Example Request
``` shell ```shell
curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/running/stats?campaign_id=1' curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/running/stats?campaign_id=1'
``` ```
##### Example Response ##### Example Response
``` json ```json
{ {
"data": [] "data": []
} }
``` ```
______________________________________________________________________
#### POST /api/campaigns
Create a new campaign.
##### Parameters
### ```POST ``` /api/campaigns | Name | Type | Required | Description |
|:-------------|:----------|:---------|:----------------------------------------------------------------------------------------|
| name | string | Yes | Campaign name. |
| subject | string | Yes | Campaign email subject. |
| lists | number\[\] | Yes | List IDs to send campaign to. |
| from_email | string | | 'From' email in campaign emails. Defaults to value from settings if not provided. |
| type | string | Yes | Campaign type: 'regular' or 'optin'. |
| content_type | string | Yes | Content type: 'richtext', 'html', 'markdown', 'plain'. |
| body | string | Yes | Content body of campaign. |
| altbody | string | | Alternate plain text body for HTML (and richtext) emails. |
| send_at | string | | Timestamp to schedule campaign. Format: 'YYYY-MM-DDTHH:MM:SS'. |
| messenger | string | | 'email' or a custom messenger defined in settings. Defaults to 'email' if not provided. |
| template_id | number | | Template ID to use. Defaults to default template if not provided. |
| tags | string\[\] | | Tags to mark campaign. |
| headers | JSON | | Key-value pairs to send as SMTP headers. Example: \[{"x-custom-header": "value"}\]. |
Creates a new campaign. ##### Example request
#### Parameters
| Name | Data type | Required/Optional | Description |
|----------------|-----------|-------------------|--------------------------------------------------------------------------------------------------------|
| `name` | String | Required | Name of the campaign. |
| `subject` | String | Required | (E-mail) subject of the campaign. |
| `lists` | []Number | Required | Array of list IDs to send the campaign to. |
| `from_email` | String | Optional | `From` e-mail to show on the campaign e-mails. If left empty, the default value from settings is used. |
| `type` | String | Required | `regular` or `optin` campaign. |
| `content_type` | String | Required | `richtext`, `html`, `markdown`, `plain` |
| `body` | String | Required | Campaign content body. |
| `altbody` | String | Optional | Alternate plain text body for HTML (and richtext) e-mails. |
| `send_at` | String | Optional | A timestamp to schedule the campaign at. Eg: `2021-12-25T06:00:00` (YYYY-MM-DDTHH:MM:SS) |
| `messenger` | String | Optional | `email` or a custom messenger defined in the settings. If left empty, `email` is used. |
| `template_id` | Number | Optional | ID of the template to use. If left empty, the default template is used. |
| `tags` | []String | Optional | Array of string tags to mark the campaign. |
| `headers` | []Map | Optional | Array of key-value pairs to be sent as SMTP headers. eg: `[{"x-custom-header": "value"}]`. |
#### Example request
```shell ```shell
curl -u "username:password" 'http://localhost:9000/api/campaigns' -X POST -H 'Content-Type: application/json;charset=utf-8' --data-raw '{"name":"Test campaign","subject":"Hello, world","lists":[1],"from_email":"listmonk <noreply@listmonk.yoursite.com>","content_type":"richtext","messenger":"email","type":"regular","tags":["test"],"template_id":1}' curl -u "username:password" 'http://localhost:9000/api/campaigns' -X POST -H 'Content-Type: application/json;charset=utf-8' --data-raw '{"name":"Test campaign","subject":"Hello, world","lists":[1],"from_email":"listmonk <noreply@listmonk.yoursite.com>","content_type":"richtext","messenger":"email","type":"regular","tags":["test"],"template_id":1}'
``` ```
#### Example response ##### Example response
```json ```json
{ {
"data": { "data": {
@ -253,24 +250,55 @@ curl -u "username:password" 'http://localhost:9000/api/campaigns' -X POST -H 'Co
} }
``` ```
______________________________________________________________________
#### ```PUT``` /api/campaigns/:`campaign_id`/status #### POST /api/campaigns/{campaign_id}/test
Modifies a campaign status to start, pause, cancel, or schedule a campaign. Test campaign with arbitrary subscribers.
##### Parameters Use the same parameters in [POST /api/campaigns](#post-apicampaigns) in addition to the below parameters.
Name | Parameter Type | Data Type | Required/Optional | Description ##### Parameters
--------------|----------------|-----------|-------------------|-------------------------------------------------------------
`campaign_id` | Path Parameter | Number | Required | The id value of the campaign whose status is to be modified.
`status` | Request Body | String | Required | `scheduled`, `running`, `paused`, `cancelled`.
###### Note: | Name | Type | Required | Description |
> * Only "scheduled" campaigns can be saved as "draft". |:------------|:---------|:---------|:---------------------------------------------------|
* Only "draft" campaigns can be "scheduled". | subscribers | string\[\] | Yes | List of subscriber e-mails to send the message to. |
* Only "paused" campaigns and "draft" campaigns can be started.
* Only "running" campaigns can be "cancelled" and "paused".
______________________________________________________________________
#### PUT /api/campaigns/{campaign_id}
Update a campaign.
> Refer to parameters from [POST /api/campaigns](#post-apicampaigns)
______________________________________________________________________
#### PUT /api/campaigns/{campaign_id}
Update a specific campaign.
> Refer to parameters from [POST /api/campaigns](#post-apicampaigns)
______________________________________________________________________
#### PUT /api/campaigns/{campaign_id}/status
Change status of a campaign.
##### Parameters
| Name | Type | Required | Description |
|:------------|:----------|:---------|:------------------------------------------------------------------------|
| campaign_id | number | Yes | Campaign ID to change status. |
| status | string | Yes | New status for campaign: 'scheduled', 'running', 'paused', 'cancelled'. |
##### Note
> - Only 'scheduled' campaigns can change status to 'draft'.
> - Only 'draft' campaigns can change status to 'scheduled'.
> - Only 'paused' and 'draft' campaigns can start ('running' status).
> - Only 'running' campaigns can change status to 'cancelled' and 'paused'.
##### Example Request ##### Example Request
@ -288,7 +316,6 @@ curl -u "username:password" -X PUT 'http://localhost:9000/api/campaigns/1/status
"id": 1, "id": 1,
"created_at": "2020-03-14T17:36:41.29451+01:00", "created_at": "2020-03-14T17:36:41.29451+01:00",
"updated_at": "2020-04-08T19:35:17.331867+01:00", "updated_at": "2020-04-08T19:35:17.331867+01:00",
"CampaignID": 0,
"views": 0, "views": 0,
"clicks": 0, "clicks": 0,
"lists": [ "lists": [
@ -318,16 +345,17 @@ curl -u "username:password" -X PUT 'http://localhost:9000/api/campaigns/1/status
} }
``` ```
#### ```DELETE``` /api/campaigns/:`campaign_id` ______________________________________________________________________
Deletes a campaign, only scheduled campaigns that have not yet been started can be deleted. #### DELETE /api/campaigns/{campaign_id}
Delete a campaign.
##### Parameters ##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description | Name | Type | Required | Description |
--------------|----------------|-----------|-------------------|------------------------------------------------- |:------------|:----------|:---------|:-----------------------|
`campaign_id` | Path Parameter | Number | Required | The id value of the campaign you want to delete. | campaign_id | number | Yes | Campaign ID to delete. |
##### Example Request ##### Example Request

63
docs/docs/content/apis/import.md
View file

@ -1,22 +1,26 @@
# API / Import # API / Import
Method | Endpoint | Description Method | Endpoint | Description
---------|--------------------------------------------------------------|---------------------------------------------------------- ---------|-------------------------------------------------|------------------------------------------------
`GET` | [api/import/subscribers](#get-apiimportsubscribers) | Gets a import statistics. GET | [/api/import/subscribers](#get-apiimportsubscribers) | Retrieve import statistics.
`GET` | [api/import/subscribers/logs](#get-apiimportsubscriberslogs) | Get a import statistics . GET | [/api/import/subscribers/logs](#get-apiimportsubscriberslogs) | Retrieve import logs.
`POST` | [api/import/subscribers](#post-apiimportsubscribers) | Upload a ZIP file or CSV file to bulk import subscribers. POST | [/api/import/subscribers](#post-apiimportsubscribers) | Upload a file for bulk subscriber import.
`DELETE` | [api/import/subscribers](#delete-apiimportsubscribers) | Stops and deletes a import. DELETE | [/api/import/subscribers](#delete-apiimportsubscribers) | Stop and remove an import.
______________________________________________________________________
#### **`GET`** api/import/subscribers #### GET /api/import/subscribers
Gets import status.
##### Example Request Retrieve the status of an import.
```shell
##### Example Request
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/import/subscribers' curl -u "username:username" -X GET 'http://localhost:9000/api/import/subscribers'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": { "data": {
@ -28,35 +32,40 @@ curl -u "username:username" -X GET 'http://localhost:9000/api/import/subscribers
} }
``` ```
#### **`GET`** api/import/subscribers/logs ______________________________________________________________________
Gets import logs.
#### GET /api/import/subscribers/logs
Retrieve logs related to imports.
##### Example Request
##### Example Request
```shell ```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/import/subscribers/logs' curl -u "username:username" -X GET 'http://localhost:9000/api/import/subscribers/logs'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": "2020/04/08 21:55:20 processing 'import.csv'\n2020/04/08 21:55:21 imported finished\n" "data": "2020/04/08 21:55:20 processing 'import.csv'\n2020/04/08 21:55:21 imported finished\n"
} }
``` ```
______________________________________________________________________
#### POST /api/import/subscribers
#### **`POST`** api/import/subscribers Send a CSV (optionally ZIP compressed) file to import subscribers. Use a multipart form POST.
Post a CSV (optionally zipped) file to do a bulk import. The request should be a multipart form POST.
##### Parameters ##### Parameters
Name | Parameter type | Data type | Required/Optional | Description | Name | Type | Required | Description |
---------|----------------|-----------|-------------------|------------------------------------ |:-------|:------------|:---------|:-----------------------------------------|
`params` | Request body | String | Required | Stringified JSON with import params | params | JSON string | Yes | Stringified JSON with import parameters. |
`file` | Request body | File | Required | File to upload | file | File | Yes | File for upload. |
***params*** (JSON string) **`params`** (JSON string)
```json ```json
{ {
@ -67,16 +76,20 @@ Name | Parameter type | Data type | Required/Optional | Description
} }
``` ```
______________________________________________________________________
#### **`DELETE`** api/import/subscribers #### DELETE /api/import/subscribers
Stops and deletes an import.
Stop and delete an ongoing import.
##### Example Request ##### Example Request
```shell ```shell
curl -u "username:username" -X DELETE 'http://localhost:9000/api/import/subscribers' curl -u "username:username" -X DELETE 'http://localhost:9000/api/import/subscribers'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": { "data": {
@ -86,4 +99,4 @@ curl -u "username:username" -X DELETE 'http://localhost:9000/api/import/subscrib
"status": "none" "status": "none"
} }
} }
``` ```

132
docs/docs/content/apis/lists.md
View file

@ -1,31 +1,37 @@
# API / Lists # API / Lists
Method | Endpoint | Description
------------|------------------------------------------------------|----------------------------------------------
`GET` | [/api/lists](#get-apilists) | Gets all lists.
`GET` | [/api/lists/:`list_id`](#get-apilistslist_id) | Gets a single list.
`POST` | [/api/lists](#post-apilists) | Creates a new list.
`PUT` | /api/lists/:`list_id` | Modifies a list.
`DELETE` | [/api/lists/:`list_id`](#put-apilistslist_id) | Deletes a list.
| Method | Endpoint | Description |
|:-------|:------------------------------------------------|:--------------------------|
| GET | [/api/lists](#get-apilists) | Retrieve all lists. |
| GET | [/api/lists/{list_id}](#get-apilistslist_id) | Retrieve a specific list. |
| POST | [/api/lists](#post-apilists) | Create a new list. |
| PUT | [/api/lists/{list_id}](#put-apilistslist_id) | Update a list. |
| DELETE | [/api/lists/{list_id}](#delete-apilistslist_id) | Delete a list. |
#### **`GET`** /api/lists ______________________________________________________________________
Gets lists.
#### GET /api/lists
Retrieve lists.
##### Parameters ##### Parameters
Name | Type | Required/Optional | Description
-----------|--------|--------------------|----------------------------------------- | Name | Type | Required | Description |
`query` | string | Optional | Optional string to search a list by name. |:---------|:----------|:---------|:-----------------------------------------------------------|
`order_by` | string | Optional | Field to sort results by. `name|status|created_at|updated_at` | query | string | | string for list name search. |
`order` | string | Optional | `ASC|DESC`Sort by ascending or descending order. | order_by | string | | Sort field. Options: name, status, created_at, updated_at. |
`page` | number | Optional | Page number for paginated results. | order | string | | Sorting order. Options: ASC, DESC. |
`per_page` | number | Optional | Results to return per page. Setting this to `all` skips pagination and returns all results. | page | number | | Page number for pagination. |
| per_page | number | | Results per page. Set to 'all' to return all results. |
##### Example Request ##### Example Request
```shell ```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/lists?page=1&per_page=100' curl -u "username:username" -X GET 'http://localhost:9000/api/lists?page=1&per_page=100'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": { "data": {
@ -62,20 +68,26 @@ curl -u "username:username" -X GET 'http://localhost:9000/api/lists?page=1&per_p
} }
``` ```
#### **`GET`** /api/lists/:`list_id` ______________________________________________________________________
Gets a single list.
#### GET /api/lists/{list_id}
Retrieve a specific list.
##### Parameters ##### Parameters
Name | Parameter type | Data type | Required/Optional | Description
----------|--------------------|-------------|---------------------|--------------------- | Name | Type | Required | Description |
`list_id` | Path parameter | number | Required | The id value of the list you want to get. |:--------|:----------|:---------|:----------------------------|
| list_id | number | Yes | ID of the list to retrieve. |
##### Example Request ##### Example Request
``` shell
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/lists/5' curl -u "username:username" -X GET 'http://localhost:9000/api/lists/5'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": { "data": {
@ -92,23 +104,29 @@ curl -u "username:username" -X GET 'http://localhost:9000/api/lists/5'
} }
``` ```
#### **`POST`** /api/lists ______________________________________________________________________
Creates a new list.
#### POST /api/lists
Create a new list.
##### Parameters ##### Parameters
Name | Parameter type | Data type | Required/Optional | Description
--------|-----------------|-------------|--------------------|---------------- | Name | Type | Required | Description |
name | Request body | string | Required | The new list name. |:------|:----------|:---------|:----------------------------------------|
type | Request body | string | Required | List type, can be set to `private` or `public`. | name | string | Yes | Name of the new list. |
optin | Request body | string | Required | `single` or `double` optin. | type | string | Yes | Type of list. Options: private, public. |
tags | Request body | string[] | Optional | The tags associated with the list. | optin | string | Yes | Opt-in type. Options: single, double. |
| tags | string\[\] | | Associated tags for a list. |
##### Example Request ##### Example Request
``` shell
```shell
curl -u "username:username" -X POST 'http://localhost:9000/api/lists' curl -u "username:username" -X POST 'http://localhost:9000/api/lists'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": { "data": {
@ -125,19 +143,24 @@ curl -u "username:username" -X POST 'http://localhost:9000/api/lists'
null null
``` ```
#### **`PUT`** /api/lists/`list_id` ______________________________________________________________________
Modifies a list.
#### PUT /api/lists/{list_id}
Update a list.
##### Parameters ##### Parameters
Name | Parameter type | Data type | Required/Optional | Description
----------|--------------------|--------------|-----------------------|------------------------- | Name | Type | Required | Description |
`list_id` | Path parameter | number | Required | The id of the list to be modified. |:--------|:----------|:---------|:----------------------------------------|
name | Request body | string | Optional | The name which the old name will be modified to. | list_id | number | Yes | ID of the list to update. |
type | Request body | string | Optional | List type, can be set to `private` or `public`. | name | string | | New name for the list. |
optin | Request body | string | Optional | `single` or `double` optin. | type | string | | Type of list. Options: private, public. |
tags | Request body | string[] | Optional | The tags associated with the list. | optin | string | | Opt-in type. Options: single, double. |
| tags | string\[\] | | Associated tags for the list. |
##### Example Request ##### Example Request
```shell ```shell
curl -u "username:username" -X PUT 'http://localhost:9000/api/lists/5' \ curl -u "username:username" -X PUT 'http://localhost:9000/api/lists/5' \
--form 'name=modified test list' \ --form 'name=modified test list' \
@ -145,7 +168,8 @@ curl -u "username:username" -X PUT 'http://localhost:9000/api/lists/5' \
``` ```
##### Example Response ##### Example Response
``` json
```json
{ {
"data": { "data": {
"id": 5, "id": 5,
@ -160,3 +184,29 @@ curl -u "username:username" -X PUT 'http://localhost:9000/api/lists/5' \
} }
} }
``` ```
______________________________________________________________________
#### DELETE /api/lists/{list_id}
Delete a specific subscriber.
##### Parameters
| Name | Type | Required | Description |
|:--------|:----------|:---------|:--------------------------|
| list_id | Number | Yes | ID of the list to delete. |
##### Example Request
```shell
curl -u 'username:password' -X DELETE 'http://localhost:9000/api/lists/1'
```
##### Example Response
```json
{
"data": true
}
```

73
docs/docs/content/apis/media.md
View file

@ -1,20 +1,26 @@
# API / Media # API / Media
Method | Endpoint | Description
---------|----------------------------------------------------|------------------------------
`GET` | [/api/media](#get-apimedia) | Gets an uploaded media file.
`POST` | [/api/media](#post-apimedia) | Uploads a media file.
`DELETE` | [/api/media/:`media_id`](#delete-apimediamedia_id) | Deletes uploaded media files.
#### **`GET`** /api/media Method | Endpoint | Description
Gets an uploaded media file. -------|------------------------------------------------|------------------------------
GET | [/api/media](#get-apimedia) | Get uploaded media file
POST | [/api/media](#post-apimedia) | Upload media file
DELETE | [/api/media/{media_id}](#delete-apimediamedia_id) | Delete uploaded media file
______________________________________________________________________
#### GET /api/media
Get an uploaded media file.
##### Example Request ##### Example Request
```shell ```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/media' \ curl -u "username:username" -X GET 'http://localhost:9000/api/media' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------093715978792575906250298' --header 'Content-Type: multipart/form-data; boundary=--------------------------093715978792575906250298'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": [ "data": [
@ -30,37 +36,29 @@ curl -u "username:username" -X GET 'http://localhost:9000/api/media' \
} }
``` ```
Response definitions ______________________________________________________________________
The following table describes each item in the response.
| Response item | Description | Data type | #### POST /api/media
|:-------------:|:----------------------------------------------------------------------------------------------|:----------------------:|
| data | Array of the media file objects, which contains an information about the uploaded media files | array |
| id | Media file object ID | number (int) |
| uuid | Media file uuid | string (uuid) |
| filename | Name of the media file | string |
| created_at | Date and time, when the media file object was created | String (localDateTime) |
| thumb_uri | The thumbnail URI of the media file | string |
| uri | URI of the media file | string |
#### **`POST`** /api/media Upload a media file.
Uploads a media file.
##### Parameters ##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description
-----|----------------|------------|-------------------|-------------------------------
file | Request body | Media file | Required | The media file to be uploaded.
| Field | Type | Required | Description |
|-------|-----------|----------|---------------------|
| file | File | Yes | Media file to upload|
##### Example Request ##### Example Request
```shell
```shell
curl -u "username:username" -X POST 'http://localhost:9000/api/media' \ curl -u "username:username" -X POST 'http://localhost:9000/api/media' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------183679989870526937212428' \ --header 'Content-Type: multipart/form-data; boundary=--------------------------183679989870526937212428' \
--form 'file=@/path/to/image.jpg' --form 'file=@/path/to/image.jpg'
``` ```
##### Example Response ##### Example Response
``` json
```json
{ {
"data": { "data": {
"id": 1, "id": 1,
@ -72,36 +70,29 @@ curl -u "username:username" -X POST 'http://localhost:9000/api/media' \
} }
} }
``` ```
Response definitions
| Response item | Description | Data type | ______________________________________________________________________
|:-------------:|:--------------------------------------------------------:|:---------:|
| data | True means that the media file was successfully uploaded | boolean |
#### **`DELETE`** /api/media/:`media_id` #### DELETE /api/media/{media_id}
Deletes an uploaded media file.
Delete an uploaded media file.
##### Parameters ##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description
-----------|----------------|-----------|-------------------|---------------------------------------------
`Media_id` | Path Parameter | Number | Required | The id of the media file you want to delete.
| Field | Type | Required | Description |
|----------|-----------|----------|-------------------------|
| media_id | number | Yes | ID of media file to delete |
##### Example Request ##### Example Request
```shell ```shell
curl -u "username:username" -X DELETE 'http://localhost:9000/api/media/1' curl -u "username:username" -X DELETE 'http://localhost:9000/api/media/1'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": true "data": true
} }
``` ```
Response definitions
| Response item | Description | Data type |
|:-------------:|:-------------------------------------------------------:|:---------:|
| data | True means that the media file was successfully deleted | boolean |

370
docs/docs/content/apis/subscribers.md
View file

@ -1,35 +1,56 @@
# API / Subscribers # API / Subscribers
Method | Endpoint | Description | Method | Endpoint | Description |
---------|-----------------------------------------------------------------------|----------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
`GET` | [/api/subscribers](#get-apisubscribers) | Gets all subscribers. | GET | [/api/subscribers](#get-apisubscribers) | Retrieve all subscribers. |
`GET` | [/api/subscribers/:`id`](#get-apisubscribersid) | Gets a single subscriber. | GET | [/api/subscribers/{subscriber_id}](#get-apisubscriberssubscriber_id) | Retrieve a specific subscriber. |
`GET` | /api/subscribers/lists/:`id` | Gets subscribers in a list. | GET | [/api/subscribers/lists/{list_id}](#get-apisubscriberslistslist_id) | Retrieve subscribers in a specific list. |
`GET` | [/api/subscribers](#get-apisubscriberslist_id) | Gets subscribers in one or more lists. | POST | [/api/subscribers](#post-apisubscribers) | Create a new subscriber. |
`GET` | [/api/subscribers](#get-apisubscribers_1) | Gets subscribers filtered by an arbitrary SQL expression. | POST | [/api/public/subscription](#post-apipublicsubscription) | Create a public subscription. |
`POST` | [/api/subscribers](#post-apisubscribers) | Creates a new subscriber. | PUT | [/api/subscribers/lists](#put-apisubscriberslists) | Modify subscriber list memberships. |
`POST` | [/api/public/subscription](#post-apipublicsubscription) | Unauthenticated API that enables public subscription. | PUT | [/api/subscribers/{subscriber_id}](#put-apisubscriberssubscriber_id) | Update a specific subscriber. |
`PUT` | [/api/subscribers/lists](#put-apisubscriberslists) | Modify subscribers' list memberships. | PUT | [/api/subscribers/{subscriber_id}/blocklist](#put-apisubscriberssubscriber_idblocklist) | Blocklist a specific subscriber. |
`PUT` | [/api/subscribers/:`id`](#put-apisubscribersid) | Updates a subscriber by ID. | PUT | /api/subscribers/blocklist | Blocklist one or more subscribers. |
`PUT` | [/api/subscribers/:`id`/blocklist](#put-apisubscribersidblocklist) | Blocklists a single subscriber. | PUT | [/api/subscribers/query/blocklist](#put-apisubscribersqueryblocklist) | Blocklist subscribers based on SQL expression. |
`PUT` | /api/subscribers/blocklist | Blocklists one or more subscribers. | DELETE | [/api/subscribers/{subscriber_id}](#delete-apisubscriberssubscriber_id) | Delete a specific subscriber. |
`PUT` | [/api/subscribers/query/blocklist](#put-apisubscribersqueryblocklist) | Blocklists subscribers with an arbitrary SQL expression. | DELETE | [/api/subscribers](#delete-apisubscribers) | Delete one or more subscribers. |
`DELETE` | [/api/subscribers/:`id`](#delete-apisubscribersid) | Deletes a single subscriber. | POST | [/api/subscribers/query/delete](#post-apisubscribersquerydelete) | Delete subscribers based on SQL expression. |
`DELETE` | [/api/subscribers](#delete-apisubscribers) | Deletes one or more subscribers .
`POST` | [/api/subscribers/query/delete](#post-apisubscribersquerydelete) | Deletes subscribers with an arbitrary SQL expression.
______________________________________________________________________
#### **`GET`** /api/subscribers #### GET /api/subscribers
Gets all subscribers.
Retrieve all subscribers.
##### Query parameters
| Name | Type | Required | Description |
|:---------|:-------|:---------|:---------------------------------------------------------------------|
| query | string | | Subscriber search term by name. |
| order_by | string | | Result sorting field. Options: name, status, created_at, updated_at. |
| order | string | | Sorting order: ASC for ascending, DESC for descending. |
| page | number | | Page number for paginated results. |
| per_page | number | | Results per page. Set as 'all' for all results. |
##### Example Request ##### Example Request
```shell ```shell
curl -u 'username:password' 'http://localhost:9000/api/subscribers?page=1&per_page=100' curl -u 'username:password' 'http://localhost:9000/api/subscribers?page=1&per_page=100'
``` ```
To skip pagination and retrieve all records, pass `per_page=all`. ```shell
curl -u 'username:password' 'http://localhost:9000/api/subscribers?list_id=1&list_id=2&page=1&per_page=100'
```
```shell
curl -u 'username:password' -X GET 'http://localhost:9000/api/subscribers' \
--url-query 'page=1' \
--url-query 'per_page=100' \
--url-query "query=subscribers.name LIKE 'Test%' AND subscribers.attribs->>'city' = 'Bengaluru'"
```
##### Example Response ##### Example Response
```json ```json
{ {
"data": { "data": {
@ -106,22 +127,26 @@ To skip pagination and retrieve all records, pass `per_page=all`.
} }
``` ```
______________________________________________________________________
#### **`GET`** /api/subscribers/:`id` #### GET /api/subscribers/{subscriber_id}
Gets a single subscriber.
Retrieve a specific subscriber.
##### Parameters ##### Parameters
Name | Parameter type |Data type | Required/Optional | Description | Name | Type | Required | Description |
---------|----------------|----------------|-------------------|----------------------- |:--------------|:----------|:---------|:-----------------|
`id` | Path parameter | Number | Required | The id value of the subscriber you want to get. | subscriber_id | Number | Yes | Subscriber's ID. |
##### Example Request ##### Example Request
```shell ```shell
curl -u 'username:password' 'http://localhost:9000/api/subscribers/1' curl -u 'username:password' 'http://localhost:9000/api/subscribers/1'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": { "data": {
@ -155,143 +180,33 @@ curl -u 'username:password' 'http://localhost:9000/api/subscribers/1'
} }
``` ```
______________________________________________________________________
#### GET /api/subscribers/lists/{list_id}
#### **`GET`** /api/subscribers Retrieve subscribers in a specific list.
Gets subscribers in one or more lists.
> Refer to the response structure in [GET /api/subscribers](#get-apisubscribers).
______________________________________________________________________
#### POST /api/subscribers
Create a new subscriber.
##### Parameters ##### Parameters
Name | Parameter type | Data type | Required/Optional | Description | Name | Type | Required | Description |
----------|-----------------|-------------|---------------------|--------------- |:-------------------------|:----------|:---------|:-----------------------------------------------------------------------------------------------------|
`List_id` | Request body | Number | Required | ID of the list to fetch subscribers from. | email | string | Yes | Subscriber's email address. |
| name | string | Yes | Subscriber's name. |
| status | string | Yes | Subscriber's status: `enabled`, `disabled`, `blocklisted`. |
| lists | number\[\] | | List of list IDs to to subscribe to. |
| attribs | JSON | | Attributes of the new subscriber. |
| preconfirm_subscriptions | bool | | If true, subscriptions are marked as confirmed and no-optin emails are sent for double opt-in lists. |
##### Example Request ##### Example Request
```shell
curl -u 'username:password' 'http://localhost:9000/api/subscribers?list_id=1&list_id=2&page=1&per_page=100'
```
To skip pagination and retrieve all records, pass `per_page=all`.
##### Example Response
```json
{
"data": {
"results": [
{
"id": 1,
"created_at": "2019-06-26T16:51:54.37065+05:30",
"updated_at": "2019-07-03T11:53:53.839692+05:30",
"uuid": "5e91dda1-1c16-467d-9bf9-2a21bf22ae21",
"email": "test@test.com",
"name": "Test Subscriber",
"attribs": {
"city": "Bengaluru",
"projects": 3,
"stack": {
"languages": ["go", "python"]
}
},
"status": "enabled",
"lists": [
{
"subscription_status": "unconfirmed",
"id": 1,
"uuid": "41badaf2-7905-4116-8eac-e8817c6613e4",
"name": "Default list",
"type": "public",
"tags": ["test"],
"created_at": "2019-06-26T16:51:54.367719+05:30",
"updated_at": "2019-06-26T16:51:54.367719+05:30"
}
]
}
],
"query": "",
"total": 1,
"per_page": 20,
"page": 1
}
}
```
#### **`GET`** /api/subscribers
Gets subscribers with an SQL expression.
##### Example Request
```shell
curl -u 'username:password' -X GET 'http://localhost:9000/api/subscribers' \
--url-query 'page=1' \
--url-query 'per_page=100' \
--url-query "query=subscribers.name LIKE 'Test%' AND subscribers.attribs->>'city' = 'Bengaluru'"
```
To skip pagination and retrieve all records, pass `per_page=all`.
>Refer to the [querying and segmentation](/docs/querying-and-segmentation#querying-and-segmenting-subscribers) section for more information on how to query subscribers with SQL expressions.
##### Example Response
```json
{
"data": {
"results": [
{
"id": 1,
"created_at": "2019-06-26T16:51:54.37065+05:30",
"updated_at": "2019-07-03T11:53:53.839692+05:30",
"uuid": "5e91dda1-1c16-467d-9bf9-2a21bf22ae21",
"email": "test@test.com",
"name": "Test Subscriber",
"attribs": {
"city": "Bengaluru",
"projects": 3,
"stack": {
"frameworks": ["echo", "go"],
"languages": ["go", "python"]
}
},
"status": "enabled",
"lists": [
{
"subscription_status": "unconfirmed",
"id": 1,
"uuid": "41badaf2-7905-4116-8eac-e8817c6613e4",
"name": "Default list",
"type": "public",
"tags": ["test"],
"created_at": "2019-06-26T16:51:54.367719+05:30",
"updated_at": "2019-06-26T16:51:54.367719+05:30"
}
]
}
],
"query": "subscribers.name LIKE 'Test%' AND subscribers.attribs-\u003e\u003e'city' = 'Bengaluru'",
"total": 1,
"per_page": 20,
"page": 1
}
}
```
#### **`POST`** /api/subscribers
Creates a new subscriber.
##### Parameters
Name | Parameter type | Data type | Required/Optional | Description
-------------------------|------------------|------------|-------------------|----------------------------
email | Request body | String | Required | The email address of the new subscriber.
name | Request body | String | Required | The name of the new subscriber.
status | Request body | String | Required | The status of the new subscriber. Can be enabled, disabled or blocklisted.
lists | Request body | Numbers | Optional | Array of list IDs to subscribe to (marked as `unconfirmed` by default).
attribs | Request body | json | Optional | JSON list containing new subscriber's attributes.
preconfirm_subscriptions | Request body | Bool | Optional | If `true`, marks subscriptions as `confirmed` and no-optin e-mails are sent for double opt-in lists.
##### Example Request
```shell ```shell
curl -u 'username:password' 'http://localhost:9000/api/subscribers' -H 'Content-Type: application/json' \ curl -u 'username:password' 'http://localhost:9000/api/subscribers' -H 'Content-Type: application/json' \
--data '{"email":"subsriber@domain.com","name":"The Subscriber","status":"enabled","lists":[1],"attribs":{"city":"Bengaluru","projects":3,"stack":{"languages":["go","python"]}}}' --data '{"email":"subsriber@domain.com","name":"The Subscriber","status":"enabled","lists":[1],"attribs":{"city":"Bengaluru","projects":3,"stack":{"languages":["go","python"]}}}'
@ -319,32 +234,35 @@ curl -u 'username:password' 'http://localhost:9000/api/subscribers' -H 'Content-
} }
``` ```
______________________________________________________________________
#### **`POST`** /api/public/subscription #### POST /api/public/subscription
This is a public, unauthenticated API meant for directly integrating forms for public subscription. The API supports both form encoded or a JSON encoded body. Create a public subscription, accepts both form encoded or JSON encoded body.
##### Parameters ##### Parameters
Name | Parameter type | Data type | Required/Optional | Description | Name | Type | Required | Description |
-------------------------|------------------|------------|-------------------|---------------------------- |:-----------|:----------|:---------|:----------------------------|
email | Request body | String | Required | The email address of the subscriber. | email | string | Yes | Subscriber's email address. |
name | Request body | String | Optional | The name of the new subscriber. | name | string | | Subscriber's name. |
list_uuids | Request body | Strings | Required | Array of list UUIDs. | list_uuids | string\[\] | Yes | List of list UUIDs. |
##### Example JSON Request ##### Example JSON Request
```shell ```shell
curl 'http://localhost:9000/api/public/subscription' -H 'Content-Type: application/json' \ curl 'http://localhost:9000/api/public/subscription' -H 'Content-Type: application/json' \
--data '{"email":"subsriber@domain.com","name":"The Subscriber","list_uuids": ["eb420c55-4cfb-4972-92ba-c93c34ba475d", "0c554cfb-eb42-4972-92ba-c93c34ba475d"]}' --data '{"email":"subsriber@domain.com","name":"The Subscriber","list_uuids": ["eb420c55-4cfb-4972-92ba-c93c34ba475d", "0c554cfb-eb42-4972-92ba-c93c34ba475d"]}'
``` ```
##### Example Form Request ##### Example Form Request
```shell ```shell
curl -u 'http://localhost:9000/api/public/subscription' \ curl -u 'http://localhost:9000/api/public/subscription' \
-d 'email=subsriber@domain.com' -d 'name=The Subscriber' -d 'l=eb420c55-4cfb-4972-92ba-c93c34ba475d' -d 'l=0c554cfb-eb42-4972-92ba-c93c34ba475d' -d 'email=subsriber@domain.com' -d 'name=The Subscriber' -d 'l=eb420c55-4cfb-4972-92ba-c93c34ba475d' -d 'l=0c554cfb-eb42-4972-92ba-c93c34ba475d'
``` ```
Notice that in form request, there param is `l` that is repeated for multiple lists, and not `lists` like in JSON. Note: For form request, use `l` for multiple lists instead of `lists`.
##### Example Response ##### Example Response
@ -354,25 +272,23 @@ Notice that in form request, there param is `l` that is repeated for multiple li
} }
``` ```
______________________________________________________________________
#### PUT /api/subscribers/lists
#### **`PUT`** /api/subscribers/lists Modify subscriber list memberships.
Modify subscribers list memberships.
##### Parameters ##### Parameters
Name | Parameter type | Data type | Required/Optional | Description | Name | Type | Required | Description |
------------------|----------------|-----------|--------------------|------------------------------------------------------- |:----------------|:----------|:-------------------|:------------------------------------------------------------------|
`ids` | Request body | Numbers | Required | The ids of the subscribers to be modified. | ids | number\[\] | Yes | Array of user IDs to be modified. |
`action` | Request body | String | Required | Whether to `add`, `remove`, or `unsubscribe` the users. | action | string | Yes | Action to be applied: `add`, `remove`, or `unsubscribe`. |
`target_list_ids` | Request body | Numbers | Required | The ids of the lists to be modified. | target_list_ids | number\[\] | Yes | Array of list IDs to be modified. |
`status` | Request body | String | Required for `add` | `confirmed`, `unconfirmed`, or `unsubscribed` status. | status | string | Required for `add` | Subscriber status: `confirmed`, `unconfirmed`, or `unsubscribed`. |
##### Example Request ##### Example Request
To subscribe users 1, 2, and 3 to lists 4, 5, and 6:
```shell ```shell
curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/lists' \ curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/lists' \
--data-raw '{"ids": [1, 2, 3], "action": "add", "target_list_ids": [4, 5, 6], "status": "confirmed"}' --data-raw '{"ids": [1, 2, 3], "action": "add", "target_list_ids": [4, 5, 6], "status": "confirmed"}'
@ -380,127 +296,137 @@ curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/lists'
##### Example Response ##### Example Response
``` json ```json
{ {
"data": true "data": true
} }
``` ```
#### **`PUT`** /api/subscribers/:`id` ______________________________________________________________________
Updates a single subscriber. #### PUT /api/subscribers/{subscriber_id}
##### Parameters Update a specific subscriber.
Parameters are the same as [POST /api/subscribers](#post-apisubscribers) used for subscriber creation. > Refer to parameters from [POST /api/subscribers](#post-apisubscribers). Note: All parameters must be set, if not, the subscriber will be removed from all previously assigned lists.
> Please note that this is a `PUT` request, so all the parameters have to be set. For example if you don't provide `lists`, the subscriber will be deleted from all the lists he was previously signed on. ______________________________________________________________________
#### **`PUT`** /api/subscribers/:`id`/blocklist #### PUT /api/subscribers/{subscriber_id}/blocklist
Blocklists a single subscriber.
##### Parameters Blocklist a specific subscriber.
Name | Parameter type | Data type | Required/Optional | Description ##### Parameters
------|----------------|------------|-------------------|-------------
`id` | Path parameter | Number | Required | The id value of the subscriber you want to blocklist.
##### Example Request | Name | Type | Required | Description |
|:--------------|:----------|:---------|:-----------------|
| subscriber_id | Number | Yes | Subscriber's ID. |
##### Example Request
```shell ```shell
curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/9/blocklist' curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/9/blocklist'
``` ```
##### Example Response ##### Example Response
``` json ```json
{ {
"data": true "data": true
} }
``` ```
#### **`PUT`** /api/subscribers/query/blocklist ______________________________________________________________________
Blocklists subscribers with an arbitrary sql expression.
#### PUT /api/subscribers/query/blocklist
Blocklist subscribers based on SQL expression.
> Refer to the [querying and segmentation](/querying-and-segmentation#querying-and-segmenting-subscribers) section for more information on how to query subscribers with SQL expressions.
##### Example Request ##### Example Request
``` shell
```shell
curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/query/blocklist' \ curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/query/blocklist' \
--data-raw '"query=subscribers.name LIKE '\''John Doe'\'' AND subscribers.attribs->>'\''city'\'' = '\''Bengaluru'\''"' --data-raw '"query=subscribers.name LIKE '\''John Doe'\'' AND subscribers.attribs->>'\''city'\'' = '\''Bengaluru'\''"'
``` ```
>Refer to the [querying and segmentation](/querying-and-segmentation#querying-and-segmenting-subscribers) section for more information on how to query subscribers with SQL expressions.
##### Example Response ##### Example Response
``` json ```json
{ {
"data": true "data": true
} }
``` ```
#### **`DELETE`** /api/subscribers/:`id` ______________________________________________________________________
Deletes a single subscriber.
##### Parameters #### DELETE /api/subscribers/{subscriber_id}
Name | Parameter type | Data type | Required/Optional | Description Delete a specific subscriber.
--------|------------------|-------------|--------------------|------------------
`id` | Path parameter | Number | Required | The id of the subscriber you want to delete.
##### Example Request ##### Parameters
``` shell | Name | Type | Required | Description |
|:--------------|:----------|:---------|:-----------------|
| subscriber_id | Number | Yes | Subscriber's ID. |
##### Example Request
```shell
curl -u 'username:password' -X DELETE 'http://localhost:9000/api/subscribers/9' curl -u 'username:password' -X DELETE 'http://localhost:9000/api/subscribers/9'
``` ```
##### Example Response ##### Example Response
``` json ```json
{ {
"data": true "data": true
} }
``` ```
#### **`DELETE`** /api/subscribers ______________________________________________________________________
Deletes one or more subscribers.
##### Parameters #### DELETE /api/subscribers
Name | Parameter type | Data type | Required/Optional | Description Delete one or more subscribers.
--------|---------------------|----------------|-----------------------|--------------
id | Query parameters | Number | Required | The id of the subscribers you want to delete. ##### Parameters
| Name | Type | Required | Description |
|:-----|:----------|:---------|:---------------------------|
| id | number\[\] | Yes | Array of subscriber's IDs. |
##### Example Request ##### Example Request
``` shell ```shell
curl -u 'username:password' -X DELETE 'http://localhost:9000/api/subscribers?id=10&id=11' curl -u 'username:password' -X DELETE 'http://localhost:9000/api/subscribers?id=10&id=11'
``` ```
##### Example Response ##### Example Response
``` json ```json
{ {
"data": true "data": true
} }
``` ```
______________________________________________________________________
#### POST /api/subscribers/query/delete
#### **`POST`** /api/subscribers/query/delete Delete subscribers based on SQL expression.
Deletes subscribers with an arbitrary SQL expression.
##### Example Request ##### Example Request
``` shell
```shell
curl -u 'username:password' -X POST 'http://localhost:9000/api/subscribers/query/delete' \ curl -u 'username:password' -X POST 'http://localhost:9000/api/subscribers/query/delete' \
--data-raw '"query=subscribers.name LIKE '\''John Doe'\'' AND subscribers.attribs->>'\''city'\'' = '\''Bengaluru'\''"' --data-raw '"query=subscribers.name LIKE '\''John Doe'\'' AND subscribers.attribs->>'\''city'\'' = '\''Bengaluru'\''"'
``` ```
>Refer to the [querying and segmentation](/querying-and-segmentation#querying-and-segmenting-subscribers) section for more information on how to query subscribers with SQL expressions.
##### Example Response ##### Example Response
``` json
```json
{ {
"data": true "data": true
} }

166
docs/docs/content/apis/templates.md
View file

@ -1,26 +1,31 @@
# API / Templates # API / Templates
Method | Endpoint | Description | Method | Endpoint | Description |
---------|------------------------------------------------------------------------------|----------------------------------------- |:-------|:------------------------------------------------------------------------------|:-------------------------------|
`GET` | [/api/templates](#get-apitemplates) | Gets all templates. | GET | [/api/templates](#get-apitemplates) | Retrieve all templates |
`GET` | [/api/templates/:`template_id`](#get-apitemplatestemplate_id) | Gets a single template. | GET | [/api/templates/{template_id}](#get-apitemplates-template_id) | Retrieve a template |
`GET` | [/api/templates/:`template_id`/preview](#get-apitemplatestemplate_idpreview) | Gets the HTML preview of a template. | GET | [/api/templates/{template_id}/preview](#get-apitemplates-template_id-preview) | Retrieve template HTML preview |
`POST` | /api/templates/preview | | POST | [/api/templates](#post-apitemplates) | Create a template |
`POST` | /api/templates | Creates a template. | POST | /api/templates/preview | Render and preview a template |
`PUT` | /api/templates/:`template_id` | Modifies a template. | PUT | [/api/templates/{template_id}](#put-apitemplatestemplate_id) | Update a template |
`PUT` | [/api/templates/:`template_id`/default](#put-apitemplatestemplate_iddefault) | Sets a template to the default template. | PUT | [/api/templates/{template_id}/default](#put-apitemplates-template_id-default) | Set default template |
`DELETE` | [/api/templates/:`template_id`](#delete-apitemplatestemplate_id) | Deletes a template. | DELETE | [/api/templates/{template_id}](#delete-apitemplates-template_id) | Delete a template |
#### **`GET`** /api/templates ______________________________________________________________________
Gets all templates.
#### GET /api/templates
Retrieve all templates.
##### Example Request ##### Example Request
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/templates' ```shell
``` curl -u "username:username" -X GET 'http://localhost:9000/api/templates'
```
##### Example Response ##### Example Response
``` json
```json
{ {
"data": [ "data": [
{ {
@ -36,20 +41,26 @@ Gets all templates.
} }
``` ```
#### **`GET`** /api/templates/:`template_id` ______________________________________________________________________
Gets a single template.
#### GET /api/templates/{template_id}
Retrieve a specific template.
##### Parameters ##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|-----------|-------------------|---------------------------------------------- | Name | Type | Required | Description |
`template_id` | Path Parameter | Number | Required | The id value of the template you want to get. |:------------|:----------|:---------|:-------------------------------|
| template_id | number | Yes | ID of the template to retrieve |
##### Example Request ##### Example Request
``` shell
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/templates/1' curl -u "username:username" -X GET 'http://localhost:9000/api/templates/1'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": { "data": {
@ -64,21 +75,27 @@ curl -u "username:username" -X GET 'http://localhost:9000/api/templates/1'
} }
``` ```
#### **`GET`** /api/templates/:`template_id`/preview ______________________________________________________________________
Gets the HTML preview of a template body.
#### GET /api/templates/{template_id}/preview
Retrieve the HTML preview of a template.
##### Parameters ##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|------------|-------------------|----------------------------------------------------------------- | Name | Type | Required | Description |
`template_id` | Path Parameter | Number | Required | The id value of the template whose html preview you want to get. |:------------|:----------|:---------|:------------------------------|
| template_id | number | Yes | ID of the template to preview |
##### Example Request ##### Example Request
``` shell
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/templates/1/preview' curl -u "username:username" -X GET 'http://localhost:9000/api/templates/1/preview'
``` ```
##### Example Response ##### Example Response
``` html
```html
<p>Hi there</p> <p>Hi there</p>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis et elit ac elit sollicitudin condimentum non a magna. <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis et elit ac elit sollicitudin condimentum non a magna.
Sed tempor mauris in facilisis vehicula. Aenean nisl urna, accumsan ac tincidunt vitae, interdum cursus massa. Sed tempor mauris in facilisis vehicula. Aenean nisl urna, accumsan ac tincidunt vitae, interdum cursus massa.
@ -93,22 +110,81 @@ curl -u "username:username" -X GET 'http://localhost:9000/api/templates/1/previe
<p>Here is a link to <a href="https://listmonk.app" target="_blank">listmonk</a>.</p> <p>Here is a link to <a href="https://listmonk.app" target="_blank">listmonk</a>.</p>
``` ```
#### **`PUT`** /api/templates/:`template_id`/default ______________________________________________________________________
Sets a template to the default template.
#### POST /api/templates
Create a template.
##### Parameters ##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|-----------|-------------------|----------------------------------------------------------------------
`template_id` | Path Parameter | Number | Required | The id value of the template you want to set to the default template.
| Name | Type | Required | Description |
|:--------|:----------|:---------|:----------------------------------------------|
| name | string | Yes | Name of the template |
| type | string | Yes | Type of the template (`campaign` or `tx`) |
| subject | string | | Subject line for the template (only for `tx`) |
| body | string | Yes | HTML body of the template |
##### Example Request ##### Example Request
``` shell
```shell
curl -u "username:password" -X POST 'http://localhost:9000/api/templates' \
-H 'Content-Type: application/json' \
-d '{
"name": "New template",
"type": "campaign",
"subject": "Your Weekly Newsletter",
"body": "<h1>Header</h1><p>Content goes here</p>"
}'
```
##### Example Response
```json
{
"data": [
{
"id": 1,
"created_at": "2020-03-14T17:36:41.288578+01:00",
"updated_at": "2020-03-14T17:36:41.288578+01:00",
"name": "Default template",
"body": "{{ template \"content\" . }}",
"type": "campaign",
"is_default": true
}
]
}
```
______________________________________________________________________
#### PUT /api/templates/{template_id}
Update a template.
> Refer to parameters from [POST /api/templates](#post-apitemplates)
______________________________________________________________________
#### PUT /api/templates/{template_id}/default
Set a template as the default.
##### Parameters
| Name | Type | Required | Description |
|:------------|:----------|:---------|:-------------------------------------|
| template_id | number | Yes | ID of the template to set as default |
##### Example Request
```shell
curl -u "username:username" -X PUT 'http://localhost:9000/api/templates/1/default' curl -u "username:username" -X PUT 'http://localhost:9000/api/templates/1/default'
``` ```
##### Example Response ##### Example Response
``` json
```json
{ {
"data": { "data": {
"id": 1, "id": 1,
@ -122,24 +198,28 @@ curl -u "username:username" -X PUT 'http://localhost:9000/api/templates/1/defaul
} }
``` ```
______________________________________________________________________
#### **`DELETE`** /api/templates/:`template_id` #### DELETE /api/templates/{template_id}
Deletes a template.
Delete a template.
##### Parameters ##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|-----------|-------------------|-------------------------------------------------
`template_id` | Path Parameter | Number | Required | The id value of the template you want to delete.
| Name | Type | Required | Description |
|:------------|:----------|:---------|:-----------------------------|
| template_id | number | Yes | ID of the template to delete |
##### Example Request ##### Example Request
``` shell
```shell
curl -u "username:username" -X DELETE 'http://localhost:9000/api/templates/35' curl -u "username:username" -X DELETE 'http://localhost:9000/api/templates/35'
``` ```
##### Example Response ##### Example Response
```json ```json
{ {
"data": true "data": true
} }
``` ```

52
docs/docs/content/apis/transactional.md
View file

@ -1,30 +1,32 @@
# API / Transactional # API / Transactional
| Method | Endpoint | Description | | Method | Endpoint | Description |
|:-------|:---------|:------------| |:-------|:---------|:-------------------------------|
| `POST` | /api/tx | | | POST | /api/tx | Send transactional messages |
______________________________________________________________________
## POST /api/tx #### POST /api/tx
Send a transactional message to one or multiple subscribers using a predefined transactional template.
Allows sending transactional messages to one or more subscribers via a preconfigured transactional template.
##### Parameters ##### Parameters
| Name | Data Type | Optional | Description |
|:--------------------|:----------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------|
| `subscriber_email` | String | Optional | E-mail of the subscriber. Either this or `subscriber_id` should be passed. |
| `subscriber_id` | Number | Optional | ID of the subscriber. Either this or `subscriber_email` should be passed. |
| `subscriber_emails` | []String | Optional | E-mails of the subscribers. This is an alternative to `subscriber_email` for multiple recipients. `["email1@example.com", "emailX@example.com"]` |
| `subscriber_ids` | []Number | Optional | IDs of the subscribers. This is an alternative to `subscriber_id` for multiple recipients. `[1,2,3]` |
| `template_id` | Number | Required | ID of the transactional template to use in the message. |
| `from_email` | String | Optional | Optional `from` email. eg: `Company <email@company.com>` |
| `data` | Map | Optional | Optional data in `{}` nested map. Available in the template as `{{ .Tx.Data.* }}` |
| `headers` | []Map | Optional | Optional array of mail headers. `[{"key": "value"}, {"key": "value"}]` |
| `messenger` | String | Optional | Messenger to use to send the message. Default value is `email`. |
| `content_type` | String | Optional | `html`, `markdown`, `plain` |
| Name | Type | Required | Description |
|:------------------|:----------|:---------|:---------------------------------------------------------------------------|
| subscriber_email | string | | Email of the subscriber. Can substitute with `subscriber_id`. |
| subscriber_id | number | | Subscriber's ID can substitute with `subscriber_email`. |
| subscriber_emails | string\[\] | | Multiple subscriber emails as alternative to `subscriber_email`. |
| subscriber_ids | number\[\] | | Multiple subscriber IDs as an alternative to `subscriber_id`. |
| template_id | number | Yes | ID of the transactional template to be used for the message. |
| from_email | string | | Optional sender email. |
| data | JSON | | Optional nested JSON map. Available in the template as `{{ .Tx.Data.* }}`. |
| headers | JSON\[\] | | Optional array of email headers. |
| messenger | string | | Messenger to send the message. Default is `email`. |
| content_type | string | | Email format options include `html`, `markdown`, and `plain`. |
##### Example
##### Request
```shell ```shell
curl -u "username:password" "http://localhost:9000/api/tx" -X POST \ curl -u "username:password" "http://localhost:9000/api/tx" -X POST \
-H 'Content-Type: application/json; charset=utf-8' \ -H 'Content-Type: application/json; charset=utf-8' \
@ -38,16 +40,19 @@ curl -u "username:password" "http://localhost:9000/api/tx" -X POST \
EOF EOF
``` ```
##### Response ##### Example response
``` json
```json
{ {
"data": true "data": true
} }
``` ```
### File Attachments ______________________________________________________________________
To include file attachments in a transactional message, use Content-Type `multipart/form-data`.
Use the parameters described above as a JSON object via the `data` form key and include an arbitrary number of attachments via the `file` key. #### File Attachments
To include file attachments in a transactional message, use the `multipart/form-data` Content-Type. Use `data` param for the parameters described above as a JSON object. Include any number of attachments via the `file` param.
```shell ```shell
curl -u "username:password" "http://localhost:9000/api/tx" -X POST \ curl -u "username:password" "http://localhost:9000/api/tx" -X POST \
@ -58,4 +63,3 @@ curl -u "username:password" "http://localhost:9000/api/tx" -X POST \
-F 'file=@"/path/to/attachment.pdf"' \ -F 'file=@"/path/to/attachment.pdf"' \
-F 'file=@"/path/to/attachment2.pdf"' -F 'file=@"/path/to/attachment2.pdf"'
``` ```

26
docs/docs/content/bounces.md
View file

@ -22,14 +22,14 @@ The bounce webhook API can be used to record bounce events with custom scripting
| `POST` | /webhooks/bounce | Record a bounce event. | | `POST` | /webhooks/bounce | Record a bounce event. |
| Name | Data type | Required/Optional | Description | | Name | Type | Required | Description |
| ----------------- | --------- | ----------------- | ------------------------------------------------------------------------------------ | | ----------------| --------- | -----------| ------------------------------------------------------------------------------------ |
| `subscriber_uuid` | String | Optional | The UUID of the subscriber. Either this or `email` is required. | | subscriber_uuid | string | | The UUID of the subscriber. Either this or `email` is required. |
| `email` | String | Optional | The e-mail of the subscriber. Either this or `subscriber_uuid` is required. | | email | string | | The e-mail of the subscriber. Either this or `subscriber_uuid` is required. |
| `campaign_uuid` | String | Optional | UUID of the campaign for which the bounce happened. | | campaign_uuid | string | | UUID of the campaign for which the bounce happened. |
| `source` | String | Required | A string indicating the source, eg: `api`, `my_script` etc. | | source | string | Yes | A string indicating the source, eg: `api`, `my_script` etc. |
| `type` | String | Required | `hard` or `soft` bounce. Currently, this has no effect on how the bounce is treated. | | type | string | Yes | `hard` or `soft` bounce. Currently, this has no effect on how the bounce is treated. |
| `meta` | String | Optional | An optional escaped JSON string with arbitrary metadata about the bounce event. | | meta | string | | An optional escaped JSON string with arbitrary metadata about the bounce event. |
```shell ```shell
@ -42,11 +42,11 @@ curl -u 'username:password' -X POST localhost:9000/webhooks/bounce \
## External webhooks ## External webhooks
listmonk supports receiving bounce webhook events from the following SMTP providers. listmonk supports receiving bounce webhook events from the following SMTP providers.
| Endpoint | Description | More info | | Endpoint | Description | More info |
|-----------------------------|------------------|-----------| |:----------------------------------------------------------|:---------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `https://listmonk.yoursite.com/webhooks/service/ses` | Amazon (AWS) SES | You can use these [Mautic steps](https://docs.mautic.org/en/channels/emails/bounce-management#amazon-webhook) as a general guide, but use your listmonk's endpoint instead. <ul> <li>When creating the *topic* select "standard" instead of the preselected "FIFO". You can put a name and leave everything else at default.</li> <li>When creating a *subscription* choose HTTPS for "Protocol", and leave *"Enable raw message delivery"* UNCHECKED.</li> <li>On the _"SES -> verified identities"_ page, make sure to check **"[include original headers](https://github.com/knadh/listmonk/issues/720#issuecomment-1046877192)"**.</li> <li>The Mautic screenshot suggests you should turn off _email feedback forwarding_, but that's completely optional depending on whether you want want email notifications.</li></ul> | | `https://listmonk.yoursite.com/webhooks/service/ses` | Amazon (AWS) SES | You can use these [Mautic steps](https://docs.mautic.org/en/channels/emails/bounce-management#amazon-webhook) as a general guide, but use your listmonk's endpoint instead. <ul> <li>When creating the *topic* select "standard" instead of the preselected "FIFO". You can put a name and leave everything else at default.</li> <li>When creating a *subscription* choose HTTPS for "Protocol", and leave *"Enable raw message delivery"* UNCHECKED.</li> <li>On the _"SES -> verified identities"_ page, make sure to check **"[include original headers](https://github.com/knadh/listmonk/issues/720#issuecomment-1046877192)"**.</li> <li>The Mautic screenshot suggests you should turn off _email feedback forwarding_, but that's completely optional depending on whether you want want email notifications.</li></ul> |
| `https://listmonk.yoursite.com/webhooks/service/sendgrid` | Sendgrid / Twilio Signed event webhook | [More info](https://docs.sendgrid.com/for-developers/tracking-events/getting-started-event-webhook-security-features) | | `https://listmonk.yoursite.com/webhooks/service/sendgrid` | Sendgrid / Twilio Signed event webhook | [More info](https://docs.sendgrid.com/for-developers/tracking-events/getting-started-event-webhook-security-features) |
| `https://listmonk.yoursite.com/webhooks/service/postmark` | Postmark webhook | [More info](https://postmarkapp.com/developer/webhooks/webhooks-overview) | `https://listmonk.yoursite.com/webhooks/service/postmark` | Postmark webhook | [More info](https://postmarkapp.com/developer/webhooks/webhooks-overview) |
## Verification ## Verification

3
docs/docs/content/static/style.css
View file

@ -106,4 +106,7 @@ by accommodating for the fixed-header's height */
.md-header--shadow { .md-header--shadow {
box-shadow: 0 4px 3px #eee; box-shadow: 0 4px 3px #eee;
transition: none; transition: none;
}
.md-header__topic:first-child {
font-weight: normal;
} }