Ghost Newsletters API

openapi: 3.1.0
info:
  title: Ghost Admin Authors Newsletters API
  description: The Ghost Admin API provides full read and write access to all content and configuration within a Ghost publication. It enables developers to create, update, and delete posts, pages, tags, members, tiers, newsletters, and offers programmatically. Authentication is handled via JSON Web Tokens generated from an Admin API key, integration tokens, or staff access tokens. The Admin API supports everything the Ghost Admin interface can do and more, making it suitable for building custom publishing workflows, content automation, member management systems, and advanced integrations.
  version: '5.0'
  contact:
    name: Ghost Foundation
    url: https://ghost.org/docs/admin-api/
  termsOfService: https://ghost.org/terms/
servers:
- url: https://{site}.ghost.io/ghost/api/admin
  description: Ghost Pro Hosted Site
  variables:
    site:
      default: your-site
      description: Your Ghost site subdomain
- url: '{protocol}://{domain}/ghost/api/admin'
  description: Self-Hosted Ghost Instance
  variables:
    protocol:
      default: https
      enum:
      - https
      - http
    domain:
      default: localhost:2368
      description: Your Ghost instance domain and port
security:
- adminApiToken: []
tags:
- name: Newsletters
  description: Manage email newsletters that members can subscribe to. Each newsletter has its own design, sender details, and subscription list.
paths:
  /newsletters/:
    get:
      operationId: adminBrowseNewsletters
      summary: Browse newsletters
      description: Retrieve a list of all newsletters configured for the publication.
      tags:
      - Newsletters
      parameters:
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/order'
      responses:
        '200':
          description: A list of newsletters
          content:
            application/json:
              schema:
                type: object
                properties:
                  newsletters:
                    type: array
                    items:
                      $ref: '#/components/schemas/Newsletter'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: adminCreateNewsletter
      summary: Create a newsletter
      description: Create a new newsletter for the publication with customizable design, sender details, and subscription settings.
      tags:
      - Newsletters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - newsletters
              properties:
                newsletters:
                  type: array
                  items:
                    $ref: '#/components/schemas/NewsletterInput'
                  minItems: 1
                  maxItems: 1
      responses:
        '201':
          description: Newsletter created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  newsletters:
                    type: array
                    items:
                      $ref: '#/components/schemas/Newsletter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /newsletters/{id}/:
    get:
      operationId: adminReadNewsletter
      summary: Read a newsletter by ID
      description: Retrieve a single newsletter by its unique identifier.
      tags:
      - Newsletters
      parameters:
      - $ref: '#/components/parameters/resourceId'
      - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: A single newsletter
          content:
            application/json:
              schema:
                type: object
                properties:
                  newsletters:
                    type: array
                    items:
                      $ref: '#/components/schemas/Newsletter'
                    minItems: 1
                    maxItems: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: adminUpdateNewsletter
      summary: Update a newsletter
      description: Update an existing newsletter by its unique identifier.
      tags:
      - Newsletters
      parameters:
      - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - newsletters
              properties:
                newsletters:
                  type: array
                  items:
                    $ref: '#/components/schemas/NewsletterInput'
                  minItems: 1
                  maxItems: 1
      responses:
        '200':
          description: Newsletter updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  newsletters:
                    type: array
                    items:
                      $ref: '#/components/schemas/Newsletter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  parameters:
    fields:
      name: fields
      in: query
      required: false
      description: Comma-separated list of fields to return in the response.
      schema:
        type: string
    page:
      name: page
      in: query
      required: false
      description: Page number for paginated results. Defaults to 1.
      schema:
        type: integer
        minimum: 1
        default: 1
    order:
      name: order
      in: query
      required: false
      description: Field and direction to order results by.
      schema:
        type: string
    filter:
      name: filter
      in: query
      required: false
      description: Apply fine-grained filters using Ghost's NQL query language.
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of resources to return per page. Defaults to 15.
      schema:
        oneOf:
        - type: integer
          minimum: 1
        - type: string
          enum:
          - all
        default: 15
    resourceId:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource
      schema:
        type: string
        format: uuid
  schemas:
    Newsletter:
      type: object
      description: A newsletter that members can subscribe to for email delivery of content.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
        uuid:
          type: string
          format: uuid
          description: Universally unique identifier
        name:
          type: string
          description: Newsletter name
        slug:
          type: string
          description: URL-safe slug
        description:
          type: string
          description: Newsletter description
          nullable: true
        sender_name:
          type: string
          description: Display name of the email sender
          nullable: true
        sender_email:
          type: string
          format: email
          description: Email address used as the sender
          nullable: true
        sender_reply_to:
          type: string
          description: Reply-to email setting
          enum:
          - newsletter
          - support
        status:
          type: string
          description: Newsletter status
          enum:
          - active
          - archived
        visibility:
          type: string
          description: Who can subscribe to this newsletter
        subscribe_on_signup:
          type: boolean
          description: Whether new members are automatically subscribed
        sort_order:
          type: integer
          description: Display order of the newsletter
          minimum: 0
        header_image:
          type: string
          format: uri
          description: Header image URL
          nullable: true
        show_header_icon:
          type: boolean
          description: Whether to show the publication icon in the header
        show_header_title:
          type: boolean
          description: Whether to show the publication title in the header
        show_header_name:
          type: boolean
          description: Whether to show the newsletter name in the header
        title_font_category:
          type: string
          description: Font category for titles
          enum:
          - serif
          - sans_serif
        title_alignment:
          type: string
          description: Title alignment
          enum:
          - center
          - left
        show_feature_image:
          type: boolean
          description: Whether to show featured images
        body_font_category:
          type: string
          description: Font category for body text
          enum:
          - serif
          - sans_serif
        footer_content:
          type: string
          description: Custom footer content
          nullable: true
        show_badge:
          type: boolean
          description: Whether to show the Ghost badge
        show_latest_posts:
          type: boolean
          description: Whether to show latest posts
        background_color:
          type: string
          description: Background color
        border_color:
          type: string
          description: Border color
          nullable: true
        title_color:
          type: string
          description: Title color
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
    NewsletterInput:
      type: object
      description: Input fields for creating or updating a newsletter.
      required:
      - name
      properties:
        name:
          type: string
          description: Newsletter name
        description:
          type: string
          description: Newsletter description
          nullable: true
        sender_name:
          type: string
          description: Display name of the sender
          nullable: true
        sender_email:
          type: string
          format: email
          description: Sender email address
          nullable: true
        sender_reply_to:
          type: string
          description: Reply-to setting
          enum:
          - newsletter
          - support
        status:
          type: string
          description: Newsletter status
          enum:
          - active
          - archived
        subscribe_on_signup:
          type: boolean
          description: Auto-subscribe new members
        sort_order:
          type: integer
          description: Display order
          minimum: 0
        header_image:
          type: string
          format: uri
          nullable: true
          description: Header image URL
        show_header_icon:
          type: boolean
          description: Show publication icon
        show_header_title:
          type: boolean
          description: Show publication title
        show_header_name:
          type: boolean
          description: Show newsletter name
        title_font_category:
          type: string
          enum:
          - serif
          - sans_serif
          description: Title font category
        body_font_category:
          type: string
          enum:
          - serif
          - sans_serif
          description: Body font category
        show_feature_image:
          type: boolean
          description: Show featured images
        show_badge:
          type: boolean
          description: Show Ghost badge
        background_color:
          type: string
          description: Background color
        border_color:
          type: string
          nullable: true
          description: Border color
        title_color:
          type: string
          nullable: true
          description: Title color
    PaginationMeta:
      type: object
      description: Pagination metadata
      properties:
        pagination:
          type: object
          properties:
            page:
              type: integer
              description: Current page
              minimum: 1
            limit:
              type: integer
              description: Items per page
              minimum: 1
            pages:
              type: integer
              description: Total pages
              minimum: 1
            total:
              type: integer
              description: Total items
              minimum: 0
            next:
              type: integer
              description: Next page number
              nullable: true
            prev:
              type: integer
              description: Previous page number
              nullable: true
    ErrorResponse:
      type: object
      description: Standard Ghost API error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: Human-readable error message
              type:
                type: string
                description: Error type identifier
              context:
                type: string
                description: Additional error context
                nullable: true
  responses:
    Unauthorized:
      description: Authentication failed or token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Request body validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    adminApiToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JSON Web Token generated from an Admin API key. The key is split into an ID and secret at the colon separator. The ID is used as the kid header and the secret is used to sign the token with HS256.
externalDocs:
  description: Ghost Admin API Documentation
  url: https://ghost.org/docs/admin-api/