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
| code |   |
| Code | |
| ----- | ------------------------------------------------------------------------ |
| `400` | Missing or bad request parameters or values |
| `403` | Session expired or invalidate. Must relogin |
| `404` | Request resource was not found |
| `405` | Request method (GET, POST etc.) is not allowed on the requested endpoint |
| `410` | The requested resource is gone permanently |
| `429` | Too many requests to the API (rate limiting) |
| `500` | Something unexpected went wrong |
| `502` | The backend OMS is down and the API is unable to communicate with it |
| `503` | Service unavailable; the API is down |
| `504` | Gateway timeout; the API is unreachable |
| 400 | Missing or bad request parameters or values |
| 403 | Session expired or invalidate. Must relogin |
| 404 | Request resource was not found |
| 405 | Request method (GET, POST etc.) is not allowed on the requested endpoint |
| 410 | The requested resource is gone permanently |
| 429 | Too many requests to the API (rate limiting) |
| 500 | Something unexpected went wrong |
| 502 | The backend OMS is down and the API is unable to communicate with it |
| 503 | Service unavailable; the API is down |
| 504 | Gateway timeout; the API is unreachable |

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

@ -1,20 +1,22 @@
# API / Campaigns
Method | Endpoint | Description
---------|------------------------------------------------------------------------------|-------------------------------------------------------------
`GET` | [/api/campaigns](#get-apicampaigns) | Gets all campaigns.
`GET` | [/api/campaigns/:`campaign_id`](#get-apicampaignscampaign_id) | Gets a single campaign.
`GET` | [/api/campaigns/:`campaign_id`/preview](#get-apicampaignscampaign_idpreview) | Gets the HTML preview of a campaign body.
`GET` | [/api/campaigns/running/stats](#get-apicampaignsrunningstats) | Gets the stats of a given set of campaigns.
`POST` | [/api/campaigns](#post-apicampaigns) | Creates a new campaign.
`POST` | /api/campaigns/:`campaign_id`/test | Posts campaign message to arbitrary subscribers for testing.
`PUT` | /api/campaigns/:`campaign_id` | Modifies a campaign.
`PUT` | [/api/campaigns/:`campaign_id`/status](#put-apicampaignscampaign_idstatus) | Start / pause / cancel / schedule a campaign.
`DELETE` | [/api/campaigns/:`campaign_id`](#delete-apicampaignscampaign_id) | Deletes a campaign.
| Method | Endpoint | Description |
|:-------|:----------------------------------------------------------------------------|:------------------------------------------|
| GET | [/api/campaigns](#get-apicampaigns) | Retrieve all campaigns. |
| GET | [/api/campaigns/{campaign_id}](#get-apicampaignscampaign_id) | Retrieve a specific campaign. |
| GET | [/api/campaigns/{campaign_id}/preview](#get-apicampaignscampaign_idpreview) | Retrieve preview of a campaign. |
| GET | [/api/campaigns/running/stats](#get-apicampaignsrunningstats) | Retrieve stats of specified campaigns. |
| POST | [/api/campaigns](#post-apicampaigns) | Create a new campaign. |
| POST | [/api/campaigns/{campaign_id}/test](#post-apicampaignscampaign_idtest) | Test campaign with arbitrary subscribers. |
| PUT | [/api/campaigns/{campaign_id}](#put-apicampaignscampaign_id) | Update a campaign. |
| PUT | [/api/campaigns/{campaign_id}/status](#put-apicampaignscampaign_idstatus) | Change status of 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
@ -23,18 +25,18 @@ Gets all campaigns.
```
##### 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
``` json
```json
{
"data": {
"results": [
@ -42,7 +44,6 @@ Gets all campaigns.
"id": 1,
"created_at": "2020-03-14T17:36:41.29451+01:00",
"updated_at": "2020-03-14T17:36:41.29451+01:00",
"CampaignID": 0,
"views": 0,
"clicks": 0,
"lists": [
@ -78,31 +79,32 @@ Gets all campaigns.
}
```
#### ```GET``` /api/campaigns/:`campaign_id`
______________________________________________________________________
Gets a single campaign.
#### GET /api/campaigns/{campaign_id}
##### Parameters
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|-----------|-------------------|-----------------------------------------------
`campaign_id` | Path Parameter | Number | Required | The id value of the campaign you want to get.
Retrieve a specific campaign.
##### Parameters
| Name | Type | Required | Description |
|:------------|:----------|:---------|:-------------|
| campaign_id | number | Yes | Campaign ID. |
##### Example Request
``` shell
```shell
curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1'
```
##### Example Response
``` json
```json
{
"data": {
"id": 1,
"created_at": "2020-03-14T17:36:41.29451+01:00",
"updated_at": "2020-03-14T17:36:41.29451+01:00",
"CampaignID": 0,
"views": 0,
"clicks": 0,
"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
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.
##### Parameters
| Name | Type | Required | Description |
|:------------|:----------|:---------|:------------------------|
| campaign_id | number | Yes | Campaign ID to preview. |
##### Example Request
@ -155,71 +154,69 @@ curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/1/previe
##### Example Response
``` html
```html
<h3>Hi John!</h3>
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
Name | Parameter Type | Data Type | Required/Optional | Description
------------|------------------|-----------|-------------------|-----------------------------------------------------------
campaign_id | Query Parameters | Number | Required | The id values of the campaigns whose stat you want to get.
| Name | Type | Required | Description |
|:------------|:----------|:---------|:-------------------------------|
| campaign_id | number | Yes | Campaign IDs to get stats for. |
##### Example Request
``` shell
```shell
curl -u "username:password" -X GET 'http://localhost:9000/api/campaigns/running/stats?campaign_id=1'
```
##### Example Response
``` json
```json
{
"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.
#### 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
##### Example request
```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}'
```
#### Example response
##### Example response
```json
{
"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
--------------|----------------|-----------|-------------------|-------------------------------------------------------------
`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`.
##### Parameters
###### Note:
> * Only "scheduled" campaigns can be saved as "draft".
* Only "draft" campaigns can be "scheduled".
* Only "paused" campaigns and "draft" campaigns can be started.
* Only "running" campaigns can be "cancelled" and "paused".
| Name | Type | Required | Description |
|:------------|:---------|:---------|:---------------------------------------------------|
| subscribers | string\[\] | Yes | List of subscriber e-mails to send the message to. |
______________________________________________________________________
#### 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
@ -288,7 +316,6 @@ curl -u "username:password" -X PUT 'http://localhost:9000/api/campaigns/1/status
"id": 1,
"created_at": "2020-03-14T17:36:41.29451+01:00",
"updated_at": "2020-04-08T19:35:17.331867+01:00",
"CampaignID": 0,
"views": 0,
"clicks": 0,
"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
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|-----------|-------------------|-------------------------------------------------
`campaign_id` | Path Parameter | Number | Required | The id value of the campaign you want to delete.
| Name | Type | Required | Description |
|:------------|:----------|:---------|:-----------------------|
| campaign_id | number | Yes | Campaign ID to delete. |
##### Example Request

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

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

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

@ -1,31 +1,37 @@
# 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
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. `name|status|created_at|updated_at`
`order` | string | Optional | `ASC|DESC`Sort by ascending or descending order.
`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 |
|:---------|:----------|:---------|:-----------------------------------------------------------|
| query | string | | string for list name search. |
| order_by | string | | Sort field. Options: name, status, created_at, updated_at. |
| order | string | | Sorting order. Options: ASC, DESC. |
| page | number | | Page number for pagination. |
| per_page | number | | Results per page. Set to 'all' to return all results. |
##### Example Request
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/lists?page=1&per_page=100'
```
##### Example Response
```json
{
"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
Name | Parameter type | Data type | Required/Optional | Description
----------|--------------------|-------------|---------------------|---------------------
`list_id` | Path parameter | number | Required | The id value of the list you want to get.
| Name | Type | Required | Description |
|:--------|:----------|:---------|:----------------------------|
| list_id | number | Yes | ID of the list to retrieve. |
##### Example Request
``` shell
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/lists/5'
```
##### Example Response
```json
{
"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
Name | Parameter type | Data type | Required/Optional | Description
--------|-----------------|-------------|--------------------|----------------
name | Request body | string | Required | The new list name.
type | Request body | string | Required | List type, can be set to `private` or `public`.
optin | Request body | string | Required | `single` or `double` optin.
tags | Request body | string[] | Optional | The tags associated with the list.
| Name | Type | Required | Description |
|:------|:----------|:---------|:----------------------------------------|
| name | string | Yes | Name of the new list. |
| type | string | Yes | Type of list. Options: private, public. |
| optin | string | Yes | Opt-in type. Options: single, double. |
| tags | string\[\] | | Associated tags for a list. |
##### Example Request
``` shell
```shell
curl -u "username:username" -X POST 'http://localhost:9000/api/lists'
```
##### Example Response
```json
{
"data": {
@ -125,19 +143,24 @@ curl -u "username:username" -X POST 'http://localhost:9000/api/lists'
null
```
#### **`PUT`** /api/lists/`list_id`
Modifies a list.
______________________________________________________________________
#### PUT /api/lists/{list_id}
Update a list.
##### Parameters
Name | Parameter type | Data type | Required/Optional | 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.
type | Request body | string | Optional | List type, can be set to `private` or `public`.
optin | Request body | string | Optional | `single` or `double` optin.
tags | Request body | string[] | Optional | The tags associated with the list.
| Name | Type | Required | Description |
|:--------|:----------|:---------|:----------------------------------------|
| list_id | number | Yes | ID of the list to update. |
| name | string | | New name for the list. |
| type | string | | Type of list. Options: private, public. |
| optin | string | | Opt-in type. Options: single, double. |
| tags | string\[\] | | Associated tags for the list. |
##### Example Request
```shell
curl -u "username:username" -X PUT 'http://localhost:9000/api/lists/5' \
--form 'name=modified test list' \
@ -145,7 +168,8 @@ curl -u "username:username" -X PUT 'http://localhost:9000/api/lists/5' \
```
##### Example Response
``` json
```json
{
"data": {
"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
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
Gets an uploaded media file.
Method | Endpoint | Description
-------|------------------------------------------------|------------------------------
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
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/media' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------093715978792575906250298'
```
##### Example Response
```json
{
"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 |
|:-------------:|:----------------------------------------------------------------------------------------------|:----------------------:|
| 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
#### **`POST`** /api/media
Uploads a media file.
Upload a media file.
##### 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
```shell
```shell
curl -u "username:username" -X POST 'http://localhost:9000/api/media' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------183679989870526937212428' \
--form 'file=@/path/to/image.jpg'
```
##### Example Response
``` json
```json
{
"data": {
"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`
Deletes an uploaded media file.
#### DELETE /api/media/{media_id}
Delete an uploaded media file.
##### 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
```shell
curl -u "username:username" -X DELETE 'http://localhost:9000/api/media/1'
```
##### Example Response
```json
{
"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
Method | Endpoint | Description
---------|-----------------------------------------------------------------------|-----------------------------------------------------------
`GET` | [/api/subscribers](#get-apisubscribers) | Gets all subscribers.
`GET` | [/api/subscribers/:`id`](#get-apisubscribersid) | Gets a single subscriber.
`GET` | /api/subscribers/lists/:`id` | Gets subscribers in a list.
`GET` | [/api/subscribers](#get-apisubscriberslist_id) | Gets subscribers in one or more lists.
`GET` | [/api/subscribers](#get-apisubscribers_1) | Gets subscribers filtered by an arbitrary SQL expression.
`POST` | [/api/subscribers](#post-apisubscribers) | Creates a new subscriber.
`POST` | [/api/public/subscription](#post-apipublicsubscription) | Unauthenticated API that enables public subscription.
`PUT` | [/api/subscribers/lists](#put-apisubscriberslists) | Modify subscribers' list memberships.
`PUT` | [/api/subscribers/:`id`](#put-apisubscribersid) | Updates a subscriber by ID.
`PUT` | [/api/subscribers/:`id`/blocklist](#put-apisubscribersidblocklist) | Blocklists a single subscriber.
`PUT` | /api/subscribers/blocklist | Blocklists one or more subscribers.
`PUT` | [/api/subscribers/query/blocklist](#put-apisubscribersqueryblocklist) | Blocklists subscribers with an arbitrary SQL expression.
`DELETE` | [/api/subscribers/:`id`](#delete-apisubscribersid) | Deletes a single subscriber.
`DELETE` | [/api/subscribers](#delete-apisubscribers) | Deletes one or more subscribers .
`POST` | [/api/subscribers/query/delete](#post-apisubscribersquerydelete) | Deletes subscribers with an arbitrary SQL expression.
| Method | Endpoint | Description |
| ------ | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
| GET | [/api/subscribers](#get-apisubscribers) | Retrieve all subscribers. |
| GET | [/api/subscribers/{subscriber_id}](#get-apisubscriberssubscriber_id) | Retrieve a specific subscriber. |
| GET | [/api/subscribers/lists/{list_id}](#get-apisubscriberslistslist_id) | Retrieve subscribers in a specific list. |
| POST | [/api/subscribers](#post-apisubscribers) | Create a new subscriber. |
| POST | [/api/public/subscription](#post-apipublicsubscription) | Create a public subscription. |
| PUT | [/api/subscribers/lists](#put-apisubscriberslists) | Modify subscriber list memberships. |
| PUT | [/api/subscribers/{subscriber_id}](#put-apisubscriberssubscriber_id) | Update a specific subscriber. |
| PUT | [/api/subscribers/{subscriber_id}/blocklist](#put-apisubscriberssubscriber_idblocklist) | Blocklist a specific subscriber. |
| PUT | /api/subscribers/blocklist | Blocklist one or more subscribers. |
| PUT | [/api/subscribers/query/blocklist](#put-apisubscribersqueryblocklist) | Blocklist subscribers based on SQL expression. |
| DELETE | [/api/subscribers/{subscriber_id}](#delete-apisubscriberssubscriber_id) | Delete a specific subscriber. |
| DELETE | [/api/subscribers](#delete-apisubscribers) | Delete one or more subscribers. |
| POST | [/api/subscribers/query/delete](#post-apisubscribersquerydelete) | Delete subscribers based on SQL expression. |
______________________________________________________________________
#### **`GET`** /api/subscribers
Gets all subscribers.
#### GET /api/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
```shell
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
```json
{
"data": {
@ -106,22 +127,26 @@ To skip pagination and retrieve all records, pass `per_page=all`.
}
```
______________________________________________________________________
#### **`GET`** /api/subscribers/:`id`
Gets a single subscriber.
#### GET /api/subscribers/{subscriber_id}
Retrieve a specific subscriber.
##### Parameters
Name | Parameter type |Data type | Required/Optional | Description
---------|----------------|----------------|-------------------|-----------------------
`id` | Path parameter | Number | Required | The id value of the subscriber you want to get.
| Name | Type | Required | Description |
|:--------------|:----------|:---------|:-----------------|
| subscriber_id | Number | Yes | Subscriber's ID. |
##### Example Request
```shell
curl -u 'username:password' 'http://localhost:9000/api/subscribers/1'
```
##### Example Response
```json
{
"data": {
@ -155,143 +180,33 @@ curl -u 'username:password' 'http://localhost:9000/api/subscribers/1'
}
```
______________________________________________________________________
#### GET /api/subscribers/lists/{list_id}
#### **`GET`** /api/subscribers
Gets subscribers in one or more lists.
Retrieve subscribers in a specific list.
> Refer to the response structure in [GET /api/subscribers](#get-apisubscribers).
______________________________________________________________________
#### POST /api/subscribers
Create a new subscriber.
##### Parameters
Name | Parameter type | Data type | Required/Optional | Description
----------|-----------------|-------------|---------------------|---------------
`List_id` | Request body | Number | Required | ID of the list to fetch subscribers from.
| Name | Type | Required | Description |
|:-------------------------|:----------|:---------|:-----------------------------------------------------------------------------------------------------|
| 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
```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
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"]}}}'
@ -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
-------------------------|------------------|------------|-------------------|----------------------------
email | Request body | String | Required | The email address of the subscriber.
name | Request body | String | Optional | The name of the new subscriber.
list_uuids | Request body | Strings | Required | Array of list UUIDs.
| Name | Type | Required | Description |
|:-----------|:----------|:---------|:----------------------------|
| email | string | Yes | Subscriber's email address. |
| name | string | | Subscriber's name. |
| list_uuids | string\[\] | Yes | List of list UUIDs. |
##### Example JSON Request
```shell
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"]}'
```
##### Example Form Request
```shell
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'
```
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
@ -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 subscribers list memberships.
Modify subscriber list memberships.
##### Parameters
Name | Parameter type | Data type | Required/Optional | Description
------------------|----------------|-----------|--------------------|-------------------------------------------------------
`ids` | Request body | Numbers | Required | The ids of the subscribers to be modified.
`action` | Request body | String | Required | Whether to `add`, `remove`, or `unsubscribe` the users.
`target_list_ids` | Request body | Numbers | Required | The ids of the lists to be modified.
`status` | Request body | String | Required for `add` | `confirmed`, `unconfirmed`, or `unsubscribed` status.
| Name | Type | Required | Description |
|:----------------|:----------|:-------------------|:------------------------------------------------------------------|
| ids | number\[\] | Yes | Array of user IDs to be modified. |
| action | string | Yes | Action to be applied: `add`, `remove`, or `unsubscribe`. |
| target_list_ids | number\[\] | Yes | Array of list IDs to be modified. |
| status | string | Required for `add` | Subscriber status: `confirmed`, `unconfirmed`, or `unsubscribed`. |
##### Example Request
To subscribe users 1, 2, and 3 to lists 4, 5, and 6:
```shell
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"}'
@ -380,127 +296,137 @@ curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/lists'
##### Example Response
``` json
```json
{
"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
Blocklists a single subscriber.
#### PUT /api/subscribers/{subscriber_id}/blocklist
##### Parameters
Blocklist a specific subscriber.
Name | Parameter type | Data type | Required/Optional | Description
------|----------------|------------|-------------------|-------------
`id` | Path parameter | Number | Required | The id value of the subscriber you want to blocklist.
##### Parameters
##### Example Request
| Name | Type | Required | Description |
|:--------------|:----------|:---------|:-----------------|
| subscriber_id | Number | Yes | Subscriber's ID. |
##### Example Request
```shell
curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/9/blocklist'
```
##### Example Response
##### Example Response
``` json
```json
{
"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
``` shell
```shell
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'\''"'
```
>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
``` json
```json
{
"data": true
}
```
#### **`DELETE`** /api/subscribers/:`id`
Deletes a single subscriber.
______________________________________________________________________
##### Parameters
#### DELETE /api/subscribers/{subscriber_id}
Name | Parameter type | Data type | Required/Optional | Description
--------|------------------|-------------|--------------------|------------------
`id` | Path parameter | Number | Required | The id of the subscriber you want to delete.
Delete a specific subscriber.
##### 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'
```
##### Example Response
##### Example Response
``` json
```json
{
"data": true
}
```
#### **`DELETE`** /api/subscribers
Deletes one or more subscribers.
______________________________________________________________________
##### Parameters
#### DELETE /api/subscribers
Name | Parameter type | Data type | Required/Optional | Description
--------|---------------------|----------------|-----------------------|--------------
id | Query parameters | Number | Required | The id of the subscribers you want to delete.
Delete one or more subscribers.
##### Parameters
| Name | Type | Required | Description |
|:-----|:----------|:---------|:---------------------------|
| id | number\[\] | Yes | Array of subscriber's IDs. |
##### Example Request
``` shell
```shell
curl -u 'username:password' -X DELETE 'http://localhost:9000/api/subscribers?id=10&id=11'
```
##### Example Response
##### Example Response
``` json
```json
{
"data": true
}
```
______________________________________________________________________
#### POST /api/subscribers/query/delete
#### **`POST`** /api/subscribers/query/delete
Deletes subscribers with an arbitrary SQL expression.
Delete subscribers based on SQL expression.
##### Example Request
``` shell
```shell
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'\''"'
```
>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
``` json
```json
{
"data": true
}

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

@ -1,26 +1,31 @@
# API / Templates
Method | Endpoint | Description
---------|------------------------------------------------------------------------------|-----------------------------------------
`GET` | [/api/templates](#get-apitemplates) | Gets all templates.
`GET` | [/api/templates/:`template_id`](#get-apitemplatestemplate_id) | Gets a single template.
`GET` | [/api/templates/:`template_id`/preview](#get-apitemplatestemplate_idpreview) | Gets the HTML preview of a template.
`POST` | /api/templates/preview |
`POST` | /api/templates | Creates a template.
`PUT` | /api/templates/:`template_id` | Modifies a template.
`PUT` | [/api/templates/:`template_id`/default](#put-apitemplatestemplate_iddefault) | Sets a template to the default template.
`DELETE` | [/api/templates/:`template_id`](#delete-apitemplatestemplate_id) | Deletes a template.
| Method | Endpoint | Description |
|:-------|:------------------------------------------------------------------------------|:-------------------------------|
| GET | [/api/templates](#get-apitemplates) | Retrieve all templates |
| GET | [/api/templates/{template_id}](#get-apitemplates-template_id) | Retrieve a template |
| GET | [/api/templates/{template_id}/preview](#get-apitemplates-template_id-preview) | Retrieve template HTML preview |
| POST | [/api/templates](#post-apitemplates) | Create a template |
| POST | /api/templates/preview | Render and preview a template |
| PUT | [/api/templates/{template_id}](#put-apitemplatestemplate_id) | Update a template |
| PUT | [/api/templates/{template_id}/default](#put-apitemplates-template_id-default) | Set default 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
```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
``` json
```json
{
"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
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|-----------|-------------------|----------------------------------------------
`template_id` | Path Parameter | Number | Required | The id value of the template you want to get.
| Name | Type | Required | Description |
|:------------|:----------|:---------|:-------------------------------|
| template_id | number | Yes | ID of the template to retrieve |
##### Example Request
``` shell
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/templates/1'
```
##### Example Response
```json
{
"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
Name | Parameter Type | Data Type | Required/Optional | Description
--------------|----------------|------------|-------------------|-----------------------------------------------------------------
`template_id` | Path Parameter | Number | Required | The id value of the template whose html preview you want to get.
| Name | Type | Required | Description |
|:------------|:----------|:---------|:------------------------------|
| template_id | number | Yes | ID of the template to preview |
##### Example Request
``` shell
```shell
curl -u "username:username" -X GET 'http://localhost:9000/api/templates/1/preview'
```
##### Example Response
``` html
```html
<p>Hi there</p>
<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.
@ -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>
```
#### **`PUT`** /api/templates/:`template_id`/default
Sets a template to the default template.
______________________________________________________________________
#### POST /api/templates
Create a template.
##### 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
``` 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'
```
##### Example Response
``` json
```json
{
"data": {
"id": 1,
@ -122,24 +198,28 @@ curl -u "username:username" -X PUT 'http://localhost:9000/api/templates/1/defaul
}
```
______________________________________________________________________
#### **`DELETE`** /api/templates/:`template_id`
Deletes a template.
#### DELETE /api/templates/{template_id}
Delete a template.
##### 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
``` shell
```shell
curl -u "username:username" -X DELETE 'http://localhost:9000/api/templates/35'
```
##### Example Response
```json
{
"data": true
}
```
```

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

@ -1,30 +1,32 @@
# API / Transactional
| Method | Endpoint | Description |
|:-------|:---------|:------------|
| `POST` | /api/tx | |
| Method | Endpoint | Description |
|:-------|:---------|:-------------------------------|
| POST | /api/tx | Send transactional messages |
______________________________________________________________________
## POST /api/tx
Send a transactional message to one or multiple subscribers using a predefined transactional template.
#### POST /api/tx
Allows sending transactional messages to one or more subscribers via a preconfigured transactional template.
##### 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
curl -u "username:password" "http://localhost:9000/api/tx" -X POST \
-H 'Content-Type: application/json; charset=utf-8' \
@ -38,16 +40,19 @@ curl -u "username:password" "http://localhost:9000/api/tx" -X POST \
EOF
```
##### Response
``` json
##### Example response
```json
{
"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
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/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. |
| Name | Data type | Required/Optional | Description |
| ----------------- | --------- | ----------------- | ------------------------------------------------------------------------------------ |
| `subscriber_uuid` | String | Optional | 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. |
| `campaign_uuid` | String | Optional | UUID of the campaign for which the bounce happened. |
| `source` | String | Required | 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. |
| `meta` | String | Optional | An optional escaped JSON string with arbitrary metadata about the bounce event. |
| Name | Type | Required | Description |
| ----------------| --------- | -----------| ------------------------------------------------------------------------------------ |
| subscriber_uuid | string | | The UUID of the subscriber. Either this or `email` is required. |
| email | string | | The e-mail of the subscriber. Either this or `subscriber_uuid` is required. |
| campaign_uuid | string | | UUID of the campaign for which the bounce happened. |
| source | string | Yes | A string indicating the source, eg: `api`, `my_script` etc. |
| type | string | Yes | `hard` or `soft` bounce. Currently, this has no effect on how the bounce is treated. |
| meta | string | | An optional escaped JSON string with arbitrary metadata about the bounce event. |
```shell
@ -42,11 +42,11 @@ curl -u 'username:password' -X POST localhost:9000/webhooks/bounce \
## External webhooks
listmonk supports receiving bounce webhook events from the following SMTP providers.
| 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/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)
| 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/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) |
## 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 {
box-shadow: 0 4px 3px #eee;
transition: none;
}
.md-header__topic:first-child {
font-weight: normal;
}