From b1fa28980e6586ac4b1cdf0031a75adaea0721e8 Mon Sep 17 00:00:00 2001 From: Felix Winterleitner <39999795+winterleitner@users.noreply.github.com> Date: Mon, 7 Aug 2023 12:59:34 +0200 Subject: [PATCH] update documentation for api/tx to include file attachments and multiple recipients (#1436) --- docs/docs/content/apis/transactional.md | 37 +++++++++++++++++-------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/docs/content/apis/transactional.md b/docs/docs/content/apis/transactional.md index 4e675579..0404f725 100644 --- a/docs/docs/content/apis/transactional.md +++ b/docs/docs/content/apis/transactional.md @@ -6,20 +6,22 @@ ## POST /api/tx -Send a transactional message to a subscriber using a predefined transactional template. +Send a transactional message to one or multiple subscribers using a predefined 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. | -| `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 | 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 @@ -43,4 +45,17 @@ EOF } ``` +### 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. + +```shell +curl -u "username:password" "http://localhost:9000/api/tx" -X POST \ +-F 'data=\"{ + \"subscriber_email\": \"user@test.com\", + \"template_id\": 4 +}"' \ +-F 'file=@"/path/to/attachment.pdf"' \ +-F 'file=@"/path/to/attachment2.pdf"' +```