apps/newsletters-api/open-api.yaml

openapi: 3.0.3
info:
  title: Newsletters API
  description: The source of truth for newsletters at The Guardian.
  version: '0.1'
  contact:
    email: newsletters-dev@guardian.co.uk

paths:
  /legacy/newsletters:
    get:
      summary: Returns a list of newsletters.
      description: Provides the legacy API format, consisting only of the array of newsletters. Includes current and previous (cancelled or paused) editorial newsletters. Does not include marketing or product newsletters.
      responses:
        '200':
          description: A JSON array of newsletter entities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LegacyNewsletter'

  /newsletters:
    get:
      summary: Returns a response object with a list of newsletters as the result field.
      description: Includes current and previous (cancelled or paused) editorial newsletters. Does not include marketing or product newsletters.
      responses:
        '200':
          description: A JSON object containing array of newsletter entities
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - total
                  - results
                properties:
                  ok:
                    type: boolean
                    example: true
                  total:
                    type: number
                    example: 1
                    description: the number of newsletters in the results
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Newsletter'

  /newsletters/{newsletterId}:
    get:
      summary: Get a newsletter by newsletterId
      parameters:
        - in: path
          name: newsletterId
          schema:
            type: string
          required: true
          description: The unique newsletterId of the newsletter to get
      responses:
        '404':
          description: A JSON object describing a 'not found' error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Returns a response object with the matching newsletters as the result field.
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                  - ok
                properties:
                  ok:
                    type: boolean
                    example: true
                  results:
                    $ref: '#/components/schemas/Newsletter'

  /drafts:
    get:
      summary: Returns a response object with a list of drafts as the result field.
      description: Includes the objects representing draft newsletters yet to be launched.
      responses:
        '200':
          description: A JSON object containing array of draft entities
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - total
                  - results
                properties:
                  ok:
                    type: boolean
                    example: true
                  total:
                    type: number
                    example: 1
                    description: the number of drafts in the results
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Draft'

  /drafts/{draftId}:
    get:
      summary: Get a draft by draftId
      parameters:
        - in: path
          name: draftId
          schema:
            type: number
          required: true
          description: The unique draftId number of the newsletter to get
      responses:
        '404':
          description: A JSON object describing a 'not found' error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Returns a response object with the matching draft as the result field.
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                  - ok
                properties:
                  ok:
                    type: boolean
                    example: true
                  results:
                    $ref: '#/components/schemas/Draft'
    delete:
      summary: Delete a draft by draftId
      parameters:
        - in: path
          name: draftId
          schema:
            type: number
          required: true
          description: The unique draftId number of the newsletter to get
      responses:
        '400':
          description: A JSON object describing a 'bad request' error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: A JSON object describing an internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Returns a response object with the draft that was deleted as the result field.
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                  - ok
                properties:
                  ok:
                    type: boolean
                    example: true
                  results:
                    $ref: '#/components/schemas/Draft'

components:
  schemas:
    Newsletter:
      type: object
      required:
        - identityName
        - name
        - status
        - theme
        - group
        - listId
        - listIdV1
        - emailEmbed
        - restricted
        - emailConfirmation
        - creationTimeStamp
      properties:
        identityName:
          type: string
          example: morning-briefing
        name:
          type: string
          example: First Edition
        status:
          type: string
          example: 'live'
        restricted:
          type: boolean
          example: false
        emailConfirmation:
          type: boolean
          example: false
        brazeNewsletterName:
          type: string
          example: Editorial_MorningBriefingUK
        brazeSubscribeAttributeName:
          type: string
          example: MorningBriefingUk_Subscribe_Email
        brazeSubscribeEventNamePrefix:
          type: string
          example: morning_briefing_uk
        theme:
          type: string
          example: News
        group:
          type: string
          example: News in brief
        description:
          type: string
          example: Archie Bland and Nimo Omer take you through the top stories and what they mean, free every weekday morning
        regionFocus:
          type: string
          example: UK
        frequency:
          type: string
          example: Every weekday
        listIdV1:
          type: integer
          example: 3640
        listId:
          type: integer
          example: 4156
        exampleUrl:
          type: string
          example: https://www.theguardian.com/world/series/guardian-morning-briefing/latest/email
        signupPage:
          type: string
          example: https://www.theguardian.com/global/2022/sep/20/sign-up-for-the-first-edition-newsletter-our-free-news-email
        illustrationCircle:
          type: string
          example: https://www.theguardian.com/global/2022/sep/20/sign-up-for-the-first-edition-newsletter-our-free-news-email
        emailEmbed:
          $ref: '#/components/schemas/EmailEmbed'
        campaignName:
          type: string
          example: MorningBriefingUK
        campaignCode:
          type: string
          example: morningbriefinguk_email
        brazeSubscribeAttributeNameAlternative:
          type: array
          items:
            type: string
            example: email_subscribe_morning_briefing_uk
        creationTimeStamp:
          type: integer
        cancellationTimeStamp:
          type: integer
    LegacyNewsletter:
      type: object
      required:
        - name
        - identityName
        - cancelled
        - theme
        - group
        - listId
        - listIdV1
        - emailEmbed
        - restricted
        - paused
        - emailConfirmation
      properties:
        identityName:
          type: string
          example: morning-briefing
        name:
          type: string
          example: First Edition
        cancelled:
          type: boolean
          example: false
        restricted:
          type: boolean
          example: false
        paused:
          type: boolean
          example: false
        emailConfirmation:
          type: boolean
          example: false
        brazeNewsletterName:
          type: string
          example: Editorial_MorningBriefingUK
        brazeSubscribeAttributeName:
          type: string
          example: MorningBriefingUk_Subscribe_Email
        brazeSubscribeEventNamePrefix:
          type: string
          example: morning_briefing_uk
        theme:
          type: string
          example: News
        group:
          type: string
          example: News in brief
        description:
          type: string
          example: Archie Bland and Nimo Omer take you through the top stories and what they mean, free every weekday morning
        regionFocus:
          type: string
          example: UK
        frequency:
          type: string
          example: Every weekday
        listIdV1:
          type: integer
          example: 3640
        listId:
          type: integer
          example: 4156
        exampleUrl:
          type: string
          example: https://www.theguardian.com/world/series/guardian-morning-briefing/latest/email
        signupPage:
          type: string
          example: https://www.theguardian.com/global/2022/sep/20/sign-up-for-the-first-edition-newsletter-our-free-news-email
        illustration:
          $ref: '#/components/schemas/NewsletterIllustration'
        emailEmbed:
          $ref: '#/components/schemas/EmailEmbed'
        campaignName:
          type: string
          example: MorningBriefingUK
        campaignCode:
          type: string
          example: morningbriefinguk_email
        brazeSubscribeAttributeNameAlternative:
          type: array
          items:
            type: string
            example: email_subscribe_morning_briefing_uk
    NewsletterIllustration:
      type: object
      required:
        - circle
      properties:
        circle:
          type: string
          example:
    EmailEmbed:
      type: object
      required:
        - name
        - title
        - successHeadline
        - successDescription
        - hexCode
      properties:
        name:
          type: string
          example: First Edition
        title:
          type: string
          example: Sign up for First Edition
        description:
          type: string
          example: Our morning email breaks down the key stories of the day, telling you what’s happening and why it matters
        successHeadline:
          type: string
          example: Subscription confirmed
        successDescription:
          type: string
          example: We'll send you First Edition every weekday
        hexCode:
          type: string
          example: '#DCDCDC'
        imageUrl:
          type: string
    ErrorResponse:
      type: object
      required:
        - ok
      properties:
        ok:
          type: boolean
          example: false
        message:
          type: string
          example: No newsletter with id fake-newsletter-id
    Draft:
      type: object
      required:
        - listId
      properties:
        listId:
          type: integer
          example: 7000
        name:
          type: string
          example: 'First edition'