update documentation for api/tx to include file attachments and multiple recipients (#1436)

Author: winterleitner

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 <[email protected]>`                          |
-| `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. `["[email protected]", "[email protected]"]` |
+| `subscriber_ids`    | []Number  | Optional | IDs of the subscribers. This is an alternative to `subscriber_id` for multiple recipients. `[1,2,3]`                                              |
+| `template_id`       | Number    | Required | ID of the transactional template to use in the message.                                                                                          |
+| `from_email`        | String    | Optional | Optional `from` email. eg: `Company <[email protected]>`                                                                                         |
+| `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\": \"[email protected]\",
+    \"template_id\": 4
+}"' \
+-F 'file=@"/path/to/attachment.pdf"' \
+-F 'file=@"/path/to/attachment2.pdf"'
+```