diff --git a/docs/docs/content/apis/apis.md b/docs/docs/content/apis/apis.md index fb4a234..b11642f 100644 --- a/docs/docs/content/apis/apis.md +++ b/docs/docs/content/apis/apis.md @@ -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 | diff --git a/docs/docs/content/apis/campaigns.md b/docs/docs/content/apis/campaigns.md index b4c24b0..b169daa 100644 --- a/docs/docs/content/apis/campaigns.md +++ b/docs/docs/content/apis/campaigns.md @@ -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

Hi John!

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 ","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 diff --git a/docs/docs/content/apis/import.md b/docs/docs/content/apis/import.md index 82b27ad..7182fa2 100644 --- a/docs/docs/content/apis/import.md +++ b/docs/docs/content/apis/import.md @@ -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" } } -``` \ No newline at end of file +``` diff --git a/docs/docs/content/apis/lists.md b/docs/docs/content/apis/lists.md index 750a691..b946962 100644 --- a/docs/docs/content/apis/lists.md +++ b/docs/docs/content/apis/lists.md @@ -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 +} +``` diff --git a/docs/docs/content/apis/media.md b/docs/docs/content/apis/media.md index c633faa..dae77b9 100644 --- a/docs/docs/content/apis/media.md +++ b/docs/docs/content/apis/media.md @@ -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 | diff --git a/docs/docs/content/apis/subscribers.md b/docs/docs/content/apis/subscribers.md index ed0f670..bed3ea3 100644 --- a/docs/docs/content/apis/subscribers.md +++ b/docs/docs/content/apis/subscribers.md @@ -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 } diff --git a/docs/docs/content/apis/templates.md b/docs/docs/content/apis/templates.md index 9f35a44..9cd06f1 100644 --- a/docs/docs/content/apis/templates.md +++ b/docs/docs/content/apis/templates.md @@ -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

Hi there

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

Here is a link to listmonk.

``` -#### **`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": "

Header

Content goes here

" +}' +``` + +##### 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 } -``` \ No newline at end of file +``` diff --git a/docs/docs/content/apis/transactional.md b/docs/docs/content/apis/transactional.md index 0404f72..130fa75 100644 --- a/docs/docs/content/apis/transactional.md +++ b/docs/docs/content/apis/transactional.md @@ -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 ` | -| `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"' ``` - diff --git a/docs/docs/content/bounces.md b/docs/docs/content/bounces.md index c13c83a..282572e 100644 --- a/docs/docs/content/bounces.md +++ b/docs/docs/content/bounces.md @@ -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. | -| `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. | +| `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 diff --git a/docs/docs/content/concepts.md b/docs/docs/content/concepts.md index ede5841..2064962 100644 --- a/docs/docs/content/concepts.md +++ b/docs/docs/content/concepts.md @@ -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). diff --git a/docs/docs/content/configuration.md b/docs/docs/content/configuration.md index ade1949..49085d3 100644 --- a/docs/docs/content/configuration.md +++ b/docs/docs/content/configuration.md @@ -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. diff --git a/docs/docs/content/external-integration.md b/docs/docs/content/external-integration.md index d402b4f..9ced11c 100644 --- a/docs/docs/content/external-integration.md +++ b/docs/docs/content/external-integration.md @@ -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 diff --git a/docs/docs/content/index.md b/docs/docs/content/index.md index be2019b..f5ee1f1 100644 --- a/docs/docs/content/index.md +++ b/docs/docs/content/index.md @@ -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. diff --git a/docs/docs/content/installation.md b/docs/docs/content/installation.md index 012dac9..db44c87 100644 --- a/docs/docs/content/installation.md +++ b/docs/docs/content/installation.md @@ -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. diff --git a/docs/docs/content/messengers.md b/docs/docs/content/messengers.md index 90fbf4c..c1cb19e 100644 --- a/docs/docs/content/messengers.md +++ b/docs/docs/content/messengers.md @@ -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 { diff --git a/docs/docs/content/static/style.css b/docs/docs/content/static/style.css index 1196e26..9d300d7 100644 --- a/docs/docs/content/static/style.css +++ b/docs/docs/content/static/style.css @@ -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; +} \ No newline at end of file diff --git a/docs/docs/content/templating.md b/docs/docs/content/templating.md index 912c39e..184d49a 100644 --- a/docs/docs/content/templating.md +++ b/docs/docs/content/templating.md @@ -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? diff --git a/docs/docs/mkdocs.yml b/docs/docs/mkdocs.yml index 2daa33a..233db6a 100644 --- a/docs/docs/mkdocs.yml +++ b/docs/docs/mkdocs.yml @@ -14,6 +14,8 @@ theme: language: 'en' feature: tabs: true + features: + - content.code.copy palette: primary: "white"