From be4be729a996aa468a344717a6129b8bde0f63ff Mon Sep 17 00:00:00 2001 From: Kailash Nadh Date: Fri, 10 Nov 2023 12:19:30 +0530 Subject: [PATCH] Refactor and clean up API Markdown docs. This has been pending for several years. Finally, managed to do with GPT-4 "auto" cleaning language and other consistency issues. 90% GPT4, 10% manual hand-wringing. GPT-4 prompt: ``` - Fix grammar, simplify language, and make language and terms consistent. - Remove superfluous language, avoid unncessary "the"s etc. - Change endpoint description in tables that list endpoints, change to terse imperative language. - Parameter / field description in Parameter tables, don't be imperative or use active sentences. Only describe the parameter passively and tersely. - Remove backticks from all headings and table values. - Format markdown tables. - Standardize "data type" columns values into number, string[], string, JSON. - Remove the "parameter type" column from tables. - Wrap ID parameters in URIs in braces. Eg: /lists/list_id to /lists/{list_id} - Add a markdown line above every API path heading that begins with GET, POST, PUT, DELETE. - Leave the lines starting with `#code-` untouched - Do not add new sections, headings, or any new content. Only edit existing content as described above. - Do not remove any sections or any existing content. ``` --- docs/docs/content/apis/apis.md | 22 +- docs/docs/content/apis/campaigns.md | 222 +++++++------- docs/docs/content/apis/import.md | 63 ++-- docs/docs/content/apis/lists.md | 132 ++++++--- docs/docs/content/apis/media.md | 73 +++-- docs/docs/content/apis/subscribers.md | 368 ++++++++++-------------- docs/docs/content/apis/templates.md | 168 ++++++++--- docs/docs/content/apis/transactional.md | 56 ++-- docs/docs/content/bounces.md | 26 +- docs/docs/content/static/style.css | 3 + 10 files changed, 614 insertions(+), 519 deletions(-) diff --git a/docs/docs/content/apis/apis.md b/docs/docs/content/apis/apis.md index fb4a2346b..b11642f31 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 b4c24b0ec..b169daa1c 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. - -#### ```GET``` /api/campaigns - -Gets all campaigns. +| 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 + +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` +______________________________________________________________________ + +#### GET /api/campaigns/{campaign_id} -Gets a single campaign. +Retrieve a specific 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 get. +##### 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 - -Gets the html preview of a campaign body. +#### GET /api/campaigns/{campaign_id}/preview -##### Parameters +Preview a specific campaign. -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 -##### Parameters +Retrieve stats of specified campaigns. -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. +##### Parameters +| 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 - -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 +| 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"}\]. | + +##### 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 } ``` +______________________________________________________________________ + +#### POST /api/campaigns/{campaign_id}/test + +Test campaign with arbitrary subscribers. + +Use the same parameters in [POST /api/campaigns](#post-apicampaigns) in addition to the below parameters. + +##### Parameters + +| Name | Type | Required | Description | +|:------------|:---------|:---------|:---------------------------------------------------| +| subscribers | string\[\] | Yes | List of subscriber e-mails to send the message to. | + +______________________________________________________________________ + +#### PUT /api/campaigns/{campaign_id} -#### ```PUT``` /api/campaigns/:`campaign_id`/status +Update a campaign. -Modifies a campaign status to start, pause, cancel, or schedule a campaign. +> Refer to parameters from [POST /api/campaigns](#post-apicampaigns) -##### 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`. +#### PUT /api/campaigns/{campaign_id} -###### 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". +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} -##### Parameters +Delete a campaign. -Name | Parameter Type | Data Type | Required/Optional | Description ---------------|----------------|-----------|-------------------|------------------------------------------------- -`campaign_id` | Path Parameter | Number | Required | The id value of the campaign you want to delete. +##### Parameters +| 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 82b27ad08..7182fa20c 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 750a6914a..b946962f3 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 c633faa1e..dae77b9d7 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} -#### **`DELETE`** /api/media/:`media_id` -Deletes an uploaded media file. +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 ed0f670ab..9a86c89fb 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. - - -#### **`GET`** /api/subscribers -Gets all subscribers. +| 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 + +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/{subscriber_id} -#### **`GET`** /api/subscribers/:`id` - Gets a single subscriber. +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. -##### Parameters +> Refer to the response structure in [GET /api/subscribers](#get-apisubscribers). -Name | Parameter type | Data type | Required/Optional | Description -----------|-----------------|-------------|---------------------|--------------- -`List_id` | Request body | Number | Required | ID of the list to fetch subscribers from. +______________________________________________________________________ -##### Example Request -```shell -curl -u 'username:password' 'http://localhost:9000/api/subscribers?list_id=1&list_id=2&page=1&per_page=100' -``` +#### POST /api/subscribers -To skip pagination and retrieve all records, pass `per_page=all`. +Create a new subscriber. -##### 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 - } -} -``` +##### Parameters -#### **`GET`** /api/subscribers -Gets subscribers with an SQL expression. +| 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' -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` +______________________________________________________________________ + +#### PUT /api/subscribers/{subscriber_id} -Updates a single subscriber. +Update a specific subscriber. -##### Parameters +> 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. -Parameters are the same as [POST /api/subscribers](#post-apisubscribers) used for subscriber creation. +______________________________________________________________________ -> 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/{subscriber_id}/blocklist -#### **`PUT`** /api/subscribers/:`id`/blocklist -Blocklists a single subscriber. +Blocklist a specific subscriber. -##### Parameters +##### Parameters -Name | Parameter type | Data type | Required/Optional | Description -------|----------------|------------|-------------------|------------- -`id` | Path parameter | Number | Required | The id value of the subscriber you want to blocklist. +| Name | Type | Required | Description | +|:--------------|:----------|:---------|:-----------------| +| subscriber_id | Number | Yes | Subscriber's ID. | -##### Example Request +##### Example Request ```shell curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/9/blocklist' ``` -##### Example Response +##### Example Response -``` json +```json { "data": true } ``` -#### **`PUT`** /api/subscribers/query/blocklist -Blocklists subscribers with an arbitrary sql expression. +______________________________________________________________________ + +#### PUT /api/subscribers/query/blocklist + +Blocklist subscribers based on SQL expression. + +> Refer to the [querying and segmentation](/querying-and-segmentation#querying-and-segmenting-subscribers) section for more information on how to query subscribers with SQL expressions. ##### Example Request -``` shell + +```shell curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/query/blocklist' \ --data-raw '"query=subscribers.name LIKE '\''John Doe'\'' AND subscribers.attribs->>'\''city'\'' = '\''Bengaluru'\''"' ``` ->Refer to the [querying and segmentation](/querying-and-segmentation#querying-and-segmenting-subscribers) section for more information on how to query subscribers with SQL expressions. - - ##### Example Response -``` json +```json { "data": true } ``` -#### **`DELETE`** /api/subscribers/:`id` -Deletes a single subscriber. +______________________________________________________________________ -##### Parameters +#### DELETE /api/subscribers/{subscriber_id} -Name | Parameter type | Data type | Required/Optional | Description ---------|------------------|-------------|--------------------|------------------ -`id` | Path parameter | Number | Required | The id of the subscriber you want to delete. +Delete a specific subscriber. -##### Example Request +##### Parameters -``` shell +| Name | Type | Required | Description | +|:--------------|:----------|:---------|:-----------------| +| subscriber_id | Number | Yes | Subscriber's ID. | + +##### Example Request + +```shell curl -u 'username:password' -X DELETE 'http://localhost:9000/api/subscribers/9' ``` -##### Example Response +##### Example Response -``` json +```json { "data": true } ``` -#### **`DELETE`** /api/subscribers -Deletes one or more subscribers. +______________________________________________________________________ -##### Parameters +#### DELETE /api/subscribers -Name | Parameter type | Data type | Required/Optional | Description ---------|---------------------|----------------|-----------------------|-------------- -id | Query parameters | Number | Required | The id of the subscribers you want to delete. +Delete one or more subscribers. + +##### Parameters + +| Name | Type | Required | Description | +|:-----|:----------|:---------|:---------------------------| +| id | number\[\] | Yes | Array of subscriber's IDs. | ##### Example Request -``` shell +```shell curl -u 'username:password' -X DELETE 'http://localhost:9000/api/subscribers?id=10&id=11' ``` -##### Example Response +##### Example Response -``` json +```json { "data": true } ``` +______________________________________________________________________ +#### POST /api/subscribers/query/delete -#### **`POST`** /api/subscribers/query/delete -Deletes subscribers with an arbitrary SQL expression. +Delete subscribers based on SQL expression. ##### Example Request -``` shell + +```shell curl -u 'username:password' -X POST 'http://localhost:9000/api/subscribers/query/delete' \ --data-raw '"query=subscribers.name LIKE '\''John Doe'\'' AND subscribers.attribs->>'\''city'\'' = '\''Bengaluru'\''"' ``` ->Refer to the [querying and segmentation](/querying-and-segmentation#querying-and-segmenting-subscribers) section for more information on how to query subscribers with SQL expressions. - - ##### Example Response -``` json + +```json { "data": true } diff --git a/docs/docs/content/apis/templates.md b/docs/docs/content/apis/templates.md index 9f35a444c..9cd06f1ba 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. - -#### **`GET`** /api/templates -Gets all templates. +| 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 + +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 | 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 +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 | 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 | +|:------------|:----------|:---------|:-------------------------------------| +| template_id | number | Yes | ID of the template to set as default | ##### Example Request -``` shell + +```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} -#### **`DELETE`** /api/templates/:`template_id` -Deletes a template. +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 0404f7254..130fa756e 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` | - - -##### Request + +| 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 + ```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 c13c83aa0..282572e5e 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.
  • When creating the *topic* select "standard" instead of the preselected "FIFO". You can put a name and leave everything else at default.
  • When creating a *subscription* choose HTTPS for "Protocol", and leave *"Enable raw message delivery"* UNCHECKED.
  • On the _"SES -> verified identities"_ page, make sure to check **"[include original headers](https://github.com/knadh/listmonk/issues/720#issuecomment-1046877192)"**.
  • The Mautic screenshot suggests you should turn off _email feedback forwarding_, but that's completely optional depending on whether you want want email notifications.
| -| `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.
  • When creating the *topic* select "standard" instead of the preselected "FIFO". You can put a name and leave everything else at default.
  • When creating a *subscription* choose HTTPS for "Protocol", and leave *"Enable raw message delivery"* UNCHECKED.
  • On the _"SES -> verified identities"_ page, make sure to check **"[include original headers](https://github.com/knadh/listmonk/issues/720#issuecomment-1046877192)"**.
  • The Mautic screenshot suggests you should turn off _email feedback forwarding_, but that's completely optional depending on whether you want want email notifications.
| +| `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/static/style.css b/docs/docs/content/static/style.css index e10ed6462..9d300d745 100644 --- a/docs/docs/content/static/style.css +++ b/docs/docs/content/static/style.css @@ -106,4 +106,7 @@ by accommodating for the fixed-header's height */ .md-header--shadow { box-shadow: 0 4px 3px #eee; transition: none; +} +.md-header__topic:first-child { + font-weight: normal; } \ No newline at end of file