Add external recipient support to /api/tx endpoint.

This patch introduces the long pending requirement of being able to send messages to arbitrary recipients via the `/api/tx` endpoint without them having to be subscribers in the database. It maintains backwards compatibility and introduces just one new field, `subscriber_mode` to the `/api/tx` endpoint. - `default` - Recipients must exist as subscribers in the database. Pass either `subscriber_emails` or `subscriber_ids`. | - `fallback` - Only accepts `subscriber_emails` and looks up subscribers in the database. If not found, sends the message to the e-mail anyway. In the template, apart from `{{ .Subscriber.Email }}`, other subscriber fields such as `.Name`. will be empty. Use `{{ Tx.Data.* }}` instead. | - `external` - Sends to the given `subscriber_emails` without subscriber lookup in the database. In the template, apart from `{{ .Subscriber.Email }}`, other subscriber fields such as `.Name`. will be empty. Use `{{ Tx.Data.* }}` instead. |
2025-12-05 16:00:03 +01:00 · 2025-11-28 14:30:19 +05:30
parent 583f92a6fc
commit 67ad4d54ce
3 changed files with 113 additions and 34 deletions
--- a/cmd/tx.go
+++ b/cmd/tx.go
@@ -87,6 +87,16 @@ func (a *App) SendTxMessage(c echo.Context) error {

 	notFound := []string{}
 	for n := range num {
+		var sub models.Subscriber
+
+		if m.SubscriberMode == models.TxSubModeExternal {
+			// `external`: Always create an ephemeral "subscriber" and don't
+			// lookup in the DB.
+			sub = models.Subscriber{
+				Email: m.SubscriberEmails[n],
+			}
+		} else {
+			// Default/fallback mode: lookup subscriber in DB.
 			var (
 				subID    int
 				subEmail string
@@ -98,17 +108,25 @@ func (a *App) SendTxMessage(c echo.Context) error {
 				subEmail = m.SubscriberEmails[n]
 			}

-		// Get the subscriber.
-		sub, err := a.core.GetSubscriber(subID, "", subEmail)
+			var err error
+			sub, err = a.core.GetSubscriber(subID, "", subEmail)
 			if err != nil {
-			// If the subscriber is not found, log that error and move on without halting on the list.
 				if er, ok := err.(*echo.HTTPError); ok && er.Code == http.StatusBadRequest {
+					// `fallback`: Create an ephemeral "subscriber" if the subscriber wasn't found.
+					if m.SubscriberMode == models.TxSubModeFallback {
+						sub = models.Subscriber{
+							Email: subEmail,
+						}
+					} else {
+						// `default`: log error and continue.
 						notFound = append(notFound, fmt.Sprintf("%v", er.Message))
 						continue
 					}
-
+				} else {
 					return err
 				}
+			}
+		}

 		// Render the message.
 		if err := m.Render(sub, tpl); err != nil {
@@ -175,10 +193,32 @@ func (a *App) validateTxMessage(m models.TxMessage) (models.TxMessage, error) {
 		m.SubscriberIDs = append(m.SubscriberIDs, m.SubscriberID)
 	}

+	// Validate subscriber_mode.
+	if m.SubscriberMode == "" {
+		m.SubscriberMode = models.TxSubModeDefault
+	}
+
+	switch m.SubscriberMode {
+	case models.TxSubModeDefault:
+		// Need subscriber_emails OR subscriber_ids, but not both.
 		if (len(m.SubscriberEmails) == 0 && len(m.SubscriberIDs) == 0) || (len(m.SubscriberEmails) > 0 && len(m.SubscriberIDs) > 0) {
 			return m, echo.NewHTTPError(http.StatusBadRequest,
 				a.i18n.Ts("globals.messages.invalidFields", "name", "send subscriber_emails OR subscriber_ids"))
 		}
+	case models.TxSubModeFallback, models.TxSubModeExternal:
+		// `fallback` and `external` can only use subscriber_emails.
+		if len(m.SubscriberIDs) > 0 {
+			return m, echo.NewHTTPError(http.StatusBadRequest,
+				a.i18n.Ts("globals.messages.invalidFields", "name", "subscriber_ids not allowed in fallback or external mode"))
+		}
+		if len(m.SubscriberEmails) == 0 {
+			return m, echo.NewHTTPError(http.StatusBadRequest,
+				a.i18n.Ts("globals.messages.invalidFields", "name", "subscriber_emails"))
+		}
+	default:
+		return m, echo.NewHTTPError(http.StatusBadRequest,
+			a.i18n.Ts("globals.messages.invalidFields", "name", "subscriber_mode"))
+	}

 	for n, email := range m.SubscriberEmails {
 		if email != "" {
--- a/docs/docs/content/apis/transactional.md
+++ b/docs/docs/content/apis/transactional.md
@@ -1,7 +1,7 @@
 # API / Transactional

 | Method | Endpoint | Description                 |
-|:-------|:---------|:-------------------------------|
+| :----- | :------- | :-------------------------- |
 | POST   | /api/tx  | Send transactional messages |

 ______________________________________________________________________
@@ -13,11 +13,12 @@ Allows sending transactional messages to one or more subscribers via a preconfig
 ##### Parameters

 | 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`.              |
+| subscriber_mode   | string     |          | Subscriber lookup mode: `default`, `fallback`, or `external`               |
 | template_id       | number     | Yes      | ID of the transactional template to be used for the message.               |
 | from_email        | string     |          | Optional sender email.                                                     |
 | subject           | string     |          | Optional subject. If empty, the subject defined on the template is used    |
@@ -26,6 +27,16 @@ Allows sending transactional messages to one or more subscribers via a preconfig
 | messenger         | string     |          | Messenger to send the message. Default is `email`.                         |
 | content_type      | string     |          | Email format options include `html`, `markdown`, and `plain`.              |

+##### Subscriber modes
+
+The `subscriber_mode` parameter controls how the recipients (subscribers or non-subscriber recipients) are resolved.
+
+| Mode       | Description                                                                                                                                                                                                                                                                    |
+| :--------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `default`  | Recipients must exist as subscribers in the database. Pass either `subscriber_emails` or `subscriber_ids`.                                                                                                                                                                     |
+| `fallback` | Only accepts `subscriber_emails` and looks up subscribers in the database. If not found, sends the message to the e-mail anyway. In the template, apart from `{{ .Subscriber.Email }}`, other subscriber fields such as `.Name`. will be empty. Use `{{ Tx.Data.* }}` instead. |
+| `external` | Sends to the given `subscriber_emails` without subscriber lookup in the database. In the template, apart from `{{ .Subscriber.Email }}`, other subscriber fields such as `.Name`. will be empty. Use `{{ Tx.Data.* }}` instead.                                                |
+
 ##### Example

 ```shell
@@ -49,6 +60,26 @@ EOF
 }
 ```

+##### Example with external mode
+
+Send to arbitrary email addresses without requiring them to be subscribers:
+
+```shell
+curl -u "api_user:token" "http://localhost:9000/api/tx" -X POST \
+     -H 'Content-Type: application/json; charset=utf-8' \
+     --data-binary @- << EOF
+    {
+        "subscriber_mode": "external",
+        "subscriber_emails": ["recipient@example.com"],
+        "template_id": 2,
+        "data": {"name": "John", "order_id": "1234"},
+        "content_type": "html"
+    }
+EOF
+```
+
+In the template, use `{{ .Tx.Data.name }}`, `{{ .Tx.Data.order_id }}`, etc. to access the data.
+
 ______________________________________________________________________

 #### File Attachments
--- a/models/messages.go
+++ b/models/messages.go
@@ -37,8 +37,16 @@ type Attachment struct {
 	Content []byte
 }

+// TxMessage subscriber modes.
+const (
+	TxSubModeDefault  = "default"
+	TxSubModeFallback = "fallback"
+	TxSubModeExternal = "external"
+)
+
 // TxMessage represents an e-mail campaign.
 type TxMessage struct {
+	SubscriberMode   string   `json:"subscriber_mode"`
 	SubscriberEmails []string `json:"subscriber_emails"`
 	SubscriberIDs    []int    `json:"subscriber_ids"`