Public/Publish-GhostPost.ps1

function Publish-GhostPost {
    <#
    .SYNOPSIS
        Publishes or schedules a post, optionally sending it by email.

    .DESCRIPTION
        Publishes a draft right away, or at a later moment with -PublishedAt.

        A post is only sent by email when -Newsletter is used. With -EmailOnly the post is sent by email but
        not published on the site. An email that was sent cannot be taken back, which is why this function asks
        for confirmation; use -Confirm:$false to publish from a script.

        When sending fails, the email property of the post reports the status failed. Revert the post with
        Unpublish-GhostPost and publish it again to retry.

    .EXAMPLE
        Publish-GhostPost -Id '5b7ada404f87d200b5b1f9c8'

        Publishes the post on the site after confirmation, without sending an email.

    .EXAMPLE
        Publish-GhostPost -Id '5b7ada404f87d200b5b1f9c8' -PublishedAt (Get-Date).AddDays(1) -Confirm:$false

        Schedules the post to be published tomorrow at this time.

    .EXAMPLE
        Get-GhostPost -Slug 'weekly-update' | Publish-GhostPost -Newsletter 'weekly' -EmailSegment 'status:-free'

        Publishes the post and sends it to the paid members of the newsletter with the slug weekly.

    .LINK
        https://docs.ghost.org/admin-api/posts/publishing-a-post

    .LINK
        https://docs.ghost.org/admin-api/posts/scheduling-a-post

    .LINK
        https://docs.ghost.org/admin-api/posts/sending-a-post

    .LINK
        https://docs.ghost.org/admin-api/posts/email-only-posts
    #>

    [CmdletBinding(DefaultParameterSetName = 'Site', SupportsShouldProcess, ConfirmImpact = 'High')]
    [OutputType('Ghost.Post')]
    param(
        # Id of the post to publish.
        [Parameter(Mandatory, Position = 0, ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [string] $Id,

        # The updated_at value of the post as it was read. Defaults to the current value of the post.
        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('updated_at')]
        [datetime] $UpdatedAt,

        # Publication date. A date in the future schedules the post, a date in the past backdates it.
        [datetime] $PublishedAt,

        # Slug of the newsletter to send the post to.
        [Parameter(Mandatory, ParameterSetName = 'Email')]
        [ValidateNotNullOrEmpty()]
        [string] $Newsletter,

        # Members to send the post to, as a filter in the Ghost query language (NQL): status:free for free
        # members, status:-free for paid members or all for everybody. Ghost sends to everybody by default.
        [Parameter(ParameterSetName = 'Email')]
        [string] $EmailSegment,

        # Send the post by email without publishing it on the site.
        [Parameter(ParameterSetName = 'Email')]
        [switch] $EmailOnly
    )

    begin {
        Test-GhostConnection
        $resources = Get-GhostAPIData -Endpoint $MyInvocation.MyCommand.Name
    }

    process {
        try {
            # A copy, so that values can be added without leaking into the next object from the pipeline.
            $parameters = [hashtable]::new($PSBoundParameters, [System.StringComparer]::OrdinalIgnoreCase)

            # A publication date in the future schedules the post; Ghost publishes it at that moment.
            $scheduled = $false
            if ($parameters.ContainsKey('PublishedAt')) {
                $scheduled = $PublishedAt.ToUniversalTime() -gt [datetime]::UtcNow
            }
            $parameters['Status'] = if ($scheduled) { 'scheduled' } else { 'published' }

            if (-not $parameters.ContainsKey('UpdatedAt')) {
                $current = @{
                    Endpoint   = $resources.URI
                    Parameters = $parameters
                    Location   = $resources.Result
                }
                $parameters['UpdatedAt'] = Get-GhostUpdatedAt @current
            }

            $uri = New-URIString -Endpoint $resources.URI -Parameters $parameters
            $uri = New-QueryString -Uri $uri -QueryKeys $resources.Query -Parameters $parameters
            $body = New-BodyString -BodyKeys $resources.Body -Parameters $parameters -Wrapper $resources.Result

            $action = 'Publish a post'
            if ($scheduled) {
                $action = 'Schedule a post for {0:u}' -f $PublishedAt.ToUniversalTime()
            }
            if ($Newsletter) {
                $action = "$action and send it to the newsletter '$Newsletter'"
            }

            if ($PSCmdlet.ShouldProcess($Id, $action)) {
                $result = Submit-Request -Uri $uri -Method $resources.Method -Body $body -Success $resources.Success
                $result = Test-ReturnFormat -Result $result -Location $resources.Result

                Set-ObjectTypeName -InputObject $result -TypeName $resources.TypeName
            }
        }
        catch {
            $PSCmdlet.ThrowTerminatingError($_)
        }
    }
}