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

Merge branch 'refactor-docs'

Browse source
This commit is contained in:
Kailash Nadh 2023-11-10 22:44:24 +05:30
parent 9e3af91dc5 e8ecdf8cde
commit 49ec11ca9c
18 changed files with 633 additions and 527 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.md#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

10
docs/docs/content/concepts.md
View file

@ -6,7 +6,7 @@ A subscriber is a recipient identified by an e-mail address and name. Subscriber
### Attributes
Attributes are arbitrary properties attached to a subscriber in addition to their e-mail and name. They are represented as a JSON map. It is not necessary for all subscribers to have the same attributes. Subscribers can be [queried and segmented](../querying-and-segmentation) into lists based on their attributes, and the attributes can be inserted into the e-mails sent to them. For example:
Attributes are arbitrary properties attached to a subscriber in addition to their e-mail and name. They are represented as a JSON map. It is not necessary for all subscribers to have the same attributes. Subscribers can be [queried and segmented](querying-and-segmentation.md) into lists based on their attributes, and the attributes can be inserted into the e-mails sent to them. For example:
```json
{
@ -35,7 +35,7 @@ A subscriber can be added to one or more lists, and each such relationship can h
### Segmentation
Segmentation is the process of filtering a large list of subscribers into a smaller group based on arbitrary conditions, primarily based on their attributes. For instance, if an e-mail needs to be sent subscribers who live in a particular city, given their city is described in their attributes, it's possible to quickly filter them out into a new list and e-mail them. [Learn more](../querying-and-segmentation).
Segmentation is the process of filtering a large list of subscribers into a smaller group based on arbitrary conditions, primarily based on their attributes. For instance, if an e-mail needs to be sent subscribers who live in a particular city, given their city is described in their attributes, it's possible to quickly filter them out into a new list and e-mail them. [Learn more](querying-and-segmentation.md).
## List
@ -53,11 +53,11 @@ A transactional message is an arbitrary message sent to a subscriber using the t
## Template
A template is a re-usable HTML design that can be used across campaigns and when sending arbitrary transactional messages. Most commonly, templates have standard header and footer areas with logos and branding elements, where campaign content is inserted in the middle. listmonk supports [Go template](https://gowebexamples.com/templates/) expressions that lets you create powerful, dynamic HTML templates. [Learn more](../templating).
A template is a re-usable HTML design that can be used across campaigns and when sending arbitrary transactional messages. Most commonly, templates have standard header and footer areas with logos and branding elements, where campaign content is inserted in the middle. listmonk supports [Go template](https://gowebexamples.com/templates/) expressions that lets you create powerful, dynamic HTML templates. [Learn more](templating.md).
## Messenger
listmonk supports multiple custom messaging backends in additional to the default SMTP e-mail backend, enabling not just e-mail campaigns, but arbitrary message campaigns such as SMS, FCM notifications etc. A *Messenger* is a web service that accepts a campaign message pushed to it as a JSON request, which the service can in turn broadcast as SMS, FCM etc. [Learn more](../messengers).
listmonk supports multiple custom messaging backends in additional to the default SMTP e-mail backend, enabling not just e-mail campaigns, but arbitrary message campaigns such as SMS, FCM notifications etc. A *Messenger* is a web service that accepts a campaign message pushed to it as a JSON request, which the service can in turn broadcast as SMS, FCM etc. [Learn more](messengers.md).
## Tracking pixel
@ -69,4 +69,4 @@ It is possible to track the clicks on every link that is sent in an e-mail. This
## Bounce
A bounce occurs when an e-mail that is sent to a recipient "bounces" back for one of many reasons including the recipient address being invalid, their mailbox being full, or the recipient's e-mail service provider marking the e-mail as spam. listmonk can automatically process such bounce e-mails that land in a configured POP mailbox, or via APIs of SMTP e-mail providers such as AWS SES and Sengrid. Based on settings, subscribers returning bounced e-mails can either be blocklisted or deleted automatically. [Learn more](../bounces).
A bounce occurs when an e-mail that is sent to a recipient "bounces" back for one of many reasons including the recipient address being invalid, their mailbox being full, or the recipient's e-mail service provider marking the e-mail as spam. listmonk can automatically process such bounce e-mails that land in a configured POP mailbox, or via APIs of SMTP e-mail providers such as AWS SES and Sengrid. Based on settings, subscribers returning bounced e-mails can either be blocklisted or deleted automatically. [Learn more](bounces.md).

6
docs/docs/content/configuration.md
View file

@ -22,7 +22,7 @@ Variables in config.toml can also be provided as environment variables prefixed
### Customizing system templates
[Read this](../templating/#system-templates)
See [system templates](templating.md#system-templates).
### HTTP routes
@ -48,9 +48,9 @@ When configuring auth proxies and web application firewalls, use this table.
| `POST` | `/webhooks/service/*` | Bounce webhook endpoints for AWS and Sendgrid |
## Media Uploads
## Media uploads
### Filesystem
#### Using filesystem
When configuring `docker` volume mounts for using filesystem media uploads, you can follow either of two approaches. [The second option may be necessary if](https://github.com/knadh/listmonk/issues/1169#issuecomment-1674475945) your setup requires you to use `sudo` for docker commands.

2
docs/docs/content/external-integration.md
View file

@ -4,7 +4,7 @@ In many environments, a mailing list manager's subscriber database is not run in
## Using APIs
The [subscriber APIs](../apis/subscribers) offers several APIs to manipulate the subscribers database, like addition, updation, and deletion. For bulk synchronisation, a CSV can be generated (and optionally zipped) and posted to the import API.
The [subscriber APIs](apis/subscribers.md) offers several APIs to manipulate the subscribers database, like addition, updation, and deletion. For bulk synchronisation, a CSV can be generated (and optionally zipped) and posted to the import API.
## Interacting directly with the DB

2
docs/docs/content/index.md
View file

@ -7,4 +7,4 @@ listmonk is a self-hosted, high performance mailing list and newsletter manager.
[![listmonk screenshot](https://user-images.githubusercontent.com/547147/134939475-e0391111-f762-44cb-b056-6cb0857755e3.png)](https://listmonk.app)
## Developers
listmonk is a free and open source software licensed under AGPLv3. If you are interested in contributing, check out the [GitHub repository](https://github.com/knadh/listmonk) and refer to the [developer setup](developer-setup). The backend is written in Go and the frontend is Vue with Buefy for UI.
listmonk is a free and open source software licensed under AGPLv3. If you are interested in contributing, check out the [GitHub repository](https://github.com/knadh/listmonk) and refer to the [developer setup](developer-setup.md). The backend is written in Go and the frontend is Vue with Buefy for UI.

2
docs/docs/content/installation.md
View file

@ -113,7 +113,7 @@ max_lifetime = "300s"
Mount the local `config.toml` inside the container at `listmonk/config.toml`.
!!! tip
- See [configuring with environment variables](../configuration) for variables like `app.admin_password` and `db.password`
- See [configuring with environment variables](configuration.md) for variables like `app.admin_password` and `db.password`
- Ensure that both `app` and `db` containers are in running. If the containers are not running, restart them `docker compose restart app db`.
- Refer to [this tutorial](https://yasoob.me/posts/setting-up-listmonk-opensource-newsletter-mailing/) for setting up a production instance with Docker + Nginx + LetsEncrypt SSL.

2
docs/docs/content/messengers.md
View file

@ -8,7 +8,7 @@ Messengers support optional BasicAuth authentication. `Plain text` format for ca
When a campaign starts, listmonk POSTs messages in the following format to the selected messenger's endpoint. The endpoint should return a `200 OK` response in case of a successful request.
The address required to broadcast the message, for instance, a phone number or an FCM ID, is expected to be stored and relayed as [subscriber attributes](../concepts/#attributes).
The address required to broadcast the message, for instance, a phone number or an FCM ID, is expected to be stored and relayed as [subscriber attributes](concepts.md/#attributes).
```json
{

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

@ -98,3 +98,15 @@ by accommodating for the fixed-header's height */
color: #666 !important;
text-decoration: underline;
}
.md-typeset hr {
background: #f6f6f6;
margin: 60px 0;
display: block;
}
.md-header--shadow {
box-shadow: 0 4px 3px #eee;
transition: none;
}
.md-header__topic:first-child {
font-weight: normal;
}

2
docs/docs/content/templating.md
View file

@ -109,7 +109,7 @@ The expression `{{ template "content" . }}` should appear exactly once in every
### Example campaign body
Campaign bodies can be composed using the built-in WYSIWYG editor or as raw HTML documents. Assuming that the subscriber has a set of [attributes defined](../querying-and-segmentation#sample-attributes), this example shows how to render those values in a campaign.
Campaign bodies can be composed using the built-in WYSIWYG editor or as raw HTML documents. Assuming that the subscriber has a set of [attributes defined](querying-and-segmentation.md#sample-attributes), this example shows how to render those values in a campaign.
```
Hey, did you notice how the template showed your first name?

2
docs/docs/mkdocs.yml
View file

@ -14,6 +14,8 @@ theme:
language: 'en'
feature:
tabs: true
features:
- content.code.copy
palette:
primary: "white"