High performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.
JavaScript campaigncampaign-managementemail-marketingemail-subscriptionlistmonkmailing-listnewsletternewsletter-managementnewsletter-softwareself-hostedsms-gatewaysmtptransactional-emails
Add `PATCH /api/subscribers/:id` to partially modify subscribers. Closes #1681.
Kailash Nadh24817d5a9384
diff --git a/cmd/handlers.go b/cmd/handlers.goindex 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.goindex 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.mdindex 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}/blocklistBlocklist a specific subscriber.