Added send_email_when_published query param to posts endpoint

no issue

- having a `send_email_when_published` property on the Post resource that only has an effect at certain times was confusing and was causing issues with clients that needed to know details of how that toggle worked
- makes `post.send_email_when_published` a fully read-only property in the API
- adds support for `?send_email_when_published=true` query param that can be passed in POST/PUT requests to the posts endpoint when scheduling or publishing a post - this is the only way to set `post.send_email_when_published` to `true`
- adds handling to ensure that `post.send_email_when_published` is always reset to `false` when reverting a post back to a draft _unless_ an email has already been sent

core/server/api/canary/posts.js

@@ -85,7 +85,8 @@ module.exports = {
         headers: {},
         options: [
             'include',
-            'source'
+            'source',
+            'send_email_when_published'
         ],
         validation: {
             options: {
@@ -120,6 +121,7 @@ module.exports = {
             'include',
             'id',
             'source',
+            'send_email_when_published',
             // NOTE: only for internal context
             'forUpdate',
             'transacting'

core/server/api/canary/utils/validators/input/schemas/posts.json

@@ -37,9 +37,6 @@
                     "type": "string",
                     "enum": ["published", "draft", "scheduled"]
                 },
-                "send_email_when_published": {
-                    "type": "boolean"
-                },
                 "locale": {
                     "type": ["string", "null"],
                     "maxLength": 6
@@ -162,6 +159,9 @@
                 },
                 "email": {
                     "strip": true
+                },
+                "send_email_when_published": {
+                    "strip": true
                 }
             }
         },

core/server/models/post.js

@@ -457,6 +457,24 @@ Post = ghostBookshelf.Model.extend({
             }
         }
 
+        // send_email_when_published is read-only and should only be set using a query param when publishing/scheduling
+        if (options.send_email_when_published && this.hasChanged('status') && (newStatus === 'published' || newStatus === 'scheduled')) {
+            this.set('send_email_when_published', true);
+        }
+
+        // ensure draft posts have the send_email_when_published reset unless an email has already been sent
+        if (newStatus === 'draft' && this.hasChanged('status')) {
+            ops.push(function ensureSendEmailWhenPublishedIsUnchanged() {
+                return self.related('email').fetch().then((email) => {
+                    if (email) {
+                        self.set('send_email_when_published', true);
+                    } else {
+                        self.set('send_email_when_published', false);
+                    }
+                });
+            });
+        }
+
         // If a title is set, not the same as the old title, a draft post, and has never been published
         if (prevTitle !== undefined && newTitle !== prevTitle && newStatus === 'draft' && !publishedAt) {
             ops.push(function updateSlug() {
@@ -760,7 +778,7 @@ Post = ghostBookshelf.Model.extend({
                 findPage: ['status'],
                 findAll: ['columns', 'filter'],
                 destroy: ['destroyAll', 'destroyBy'],
-                edit: ['filter']
+                edit: ['filter', 'send_email_when_published']
             };
 
         // The post model additionally supports having a formats option