Skip to content

High performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.

Add `PATCH /api/subscribers/:id` to partially modify subscribers. Closes #1681.

Kailash Nadh24817d5a9384
diff --git a/cmd/handlers.go b/cmd/handlers.go
index 2efdc795..c89408a2 100644
--- a/cmd/handlers.go
+++ b/cmd/handlers.go
@@ -122,6 +122,7 @@ func initHTTPHandlers(e *echo.Echo, a *App) {
g.DELETE("/api/subscribers/:id/bounces", pm(hasID(a.DeleteSubscriberBounces), "bounces:manage"))
g.POST("/api/subscribers", pm(a.CreateSubscriber, "subscribers:manage"))
g.PUT("/api/subscribers/:id", pm(hasID(a.UpdateSubscriber), "subscribers:manage"))
+ g.PATCH("/api/subscribers/:id", pm(hasID(a.PatchSubscriber), "subscribers:manage"))
g.POST("/api/subscribers/:id/optin", pm(hasID(a.SubscriberSendOptin), "subscribers:manage"))
g.PUT("/api/subscribers/blocklist", pm(a.BlocklistSubscribers, "subscribers:manage"))
g.PUT("/api/subscribers/:id/blocklist", pm(hasID(a.BlocklistSubscriber), "subscribers:manage"))
diff --git a/cmd/subscribers.go b/cmd/subscribers.go
index a4de8afe..9bb1546d 100644
--- a/cmd/subscribers.go
+++ b/cmd/subscribers.go
@@ -301,6 +301,67 @@ func (a *App) UpdateSubscriber(c echo.Context) error {
return c.JSON(http.StatusOK, okResp{out})
}
+// PatchSubscriber handles partially modifying a subscriber.
+// Only fields present in the request body are updated.
+func (a *App) PatchSubscriber(c echo.Context) error {
+ user := auth.GetUser(c)
+ id := getID(c)
+
+ // Fetch the sub subscriber from the DB.
+ sub, err := a.core.GetSubscriber(id, "", "")
+ if err != nil {
+ return err
+ }
+
+ // Prepopulate the incoming request struct with existing values.
+ // Rather than tediously and conditionally checking each incoming field, we can simply
+ // overwrite everything in the DB with the incoming fields+existing fields.
+ req := struct {
+ models.Subscriber
+ Lists *[]int `json:"lists"`
+ PreconfirmSubs bool `json:"preconfirm_subscriptions"`
+ }{
+ Subscriber: sub,
+ }
+
+ if err := c.Bind(&req); err != nil {
+ return err
+ }
+
+ if em, err := a.importer.SanitizeEmail(req.Email); err != nil {
+ return echo.NewHTTPError(http.StatusBadRequest, err.Error())
+ } else {
+ req.Email = em
+ }
+
+ if req.Name != "" && !strHasLen(req.Name, 1, stdInputMaxLen) {
+ return echo.NewHTTPError(http.StatusBadRequest, a.i18n.T("subscribers.invalidName"))
+ }
+
+ // If lists were explicitly sent, replace the existing subscriptions.
+ overwriteSubs := false
+ var listIDs []int
+ if req.Lists != nil {
+ overwriteSubs = true
+ listIDs = user.FilterListsByPerm(auth.PermTypeManage, *req.Lists)
+ if len(*req.Lists) > 0 && len(listIDs) == 0 {
+ return echo.NewHTTPError(http.StatusForbidden, a.i18n.Ts("globals.messages.permissionDenied", "name", "lists"))
+ }
+ }
+
+ allPerm, permittedLists := user.GetPermittedLists(auth.PermTypeManage)
+ if allPerm {
+ permittedLists = []int{}
+ }
+
+ out, _, err := a.core.UpdateSubscriberWithLists(id, req.Subscriber, listIDs, nil, req.PreconfirmSubs, overwriteSubs, false, permittedLists)
+ if err != nil {
+ return err
+ }
+
+ return c.JSON(http.StatusOK, okResp{out})
+}
+
// SubscriberSendOptin sends an optin confirmation e-mail to a subscriber.
func (a *App) SubscriberSendOptin(c echo.Context) error {
user := auth.GetUser(c)
diff --git a/docs/docs/content/apis/subscribers.md b/docs/docs/content/apis/subscribers.md
index fa985b7b..bdae3d78 100644
--- a/docs/docs/content/apis/subscribers.md
+++ b/docs/docs/content/apis/subscribers.md
@@ -11,6 +11,7 @@
| 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. |
+| PATCH | [/api/subscribers/{subscriber_id}](#patch-apisubscriberssubscriber_id) | Partially update a specific subscriber. |
| PUT | [/api/subscribers/{subscriber_id}/blocklist](#put-apisubscriberssubscriber_idblocklist) | Blocklist a specific subscriber. |
| PUT | [/api/subscribers/blocklist](#put-apisubscribersblocklist) | Blocklist one or many subscribers. |
| PUT | [/api/subscribers/query/blocklist](#put-apisubscribersqueryblocklist) | Blocklist subscribers based on SQL expression. |
@@ -437,6 +438,56 @@ Update a specific subscriber.
______________________________________________________________________
+#### PATCH /api/subscribers/{subscriber_id}
+
+Partially update a subscriber. Only fields present in the request body are updated. Unlike PUT, omitting the `lists` field preserves existing list subscriptions. `PUT` treats empty `lists` as a signal to clear all subscriptions.
+
+##### Parameters
+
+| Name | Type | Required | Description |
+|:-------------------------|:-----------|:---------|:----------------------------------------------------------------------------------------------------------------------------------|
+| email | string | | Subscriber's email address. Updated only if provided. |
+| name | string | | Subscriber's name. Updated only if provided. |
+| status | string | | Subscriber's status: `enabled`, `disabled`, `blocklisted`. Updated only if provided. |
+| lists | number\[\] | | Array of list IDs. If provided, replaces the subscriber's current list subscriptions. If omitted, existing subscriptions are kept. |
+| attribs | JSON | | JSON object of subscriber attributes. If provided, merged with existing attributes. |
+| preconfirm_subscriptions | bool | | If true, subscriptions are marked as confirmed and no opt-in emails are sent for double opt-in lists. |
+
+##### Example Request
+
+```shell
+curl -u 'api_username:access_token' -X PATCH 'http://localhost:9000/api/subscribers/1' \
+ -H 'Content-Type: application/json' \
+ --data '{"name":"Updated Name"}'
+```
+
+##### Example Response
+
+```json
+{
+ "data": {
+ "id": 1,
+ "created_at": "2020-02-10T23:07:16.199433+01:00",
+ "updated_at": "2020-03-10T16:37:17.228327+01:00",
+ "uuid": "ea06b2e7-4b08-4571-b436-5c5cf31c5cd4",
+ "email": "[email protected]",
+ "name": "Updated Name",
+ "attribs": {},
+ "status": "enabled",
+ "lists": [{
+ "subscription_status": "unconfirmed",
+ "id": 1,
+ "uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
+ "name": "Default list",
+ "type": "public",
+ "optin": "single"
+ }]
+ }
+}
+```
+
+______________________________________________________________________
+
#### PUT /api/subscribers/{subscriber_id}/blocklist
Blocklist a specific subscriber.