openapi: 3.0.1
info:
  title: Plunk API
  description: >-
    The Plunk REST API for the open-source email platform for SaaS. Plunk unifies
    transactional email (send), event tracking for automations (track), contact /
    subscriber management, and marketing campaigns behind a single Bearer-authenticated
    API. Public API routes under /v1 return a wrapped envelope ({"success": true,
    "data": ...}); most routes require a secret key (sk_), while /v1/track may also
    be called with a public key (pk_) for client-side use. The same API is served
    by the hosted platform and by self-hosted (AGPL-3.0) deployments.
  termsOfService: https://www.useplunk.com/legal/terms
  contact:
    name: Plunk Support
    url: https://docs.useplunk.com
  license:
    name: AGPL-3.0
    url: https://github.com/useplunk/plunk/blob/main/LICENSE
  version: '1.0'
servers:
  - url: https://api.useplunk.com/v1
    description: Plunk hosted API
security:
  - bearerAuth: []
tags:
  - name: Transactional
    description: Send transactional email.
  - name: Events
    description: Track contact events that drive automations.
  - name: Contacts
    description: Manage contacts and their subscription state.
  - name: Campaigns
    description: Create and send marketing campaigns.
paths:
  /send:
    post:
      operationId: sendEmail
      tags:
        - Transactional
      summary: Send a transactional email
      description: >-
        Sends a single transactional email to one or more recipients using a
        secret API key. The body may be HTML or plain text. Optional fields allow
        overriding the sender, reply-to, custom headers, and attachments.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
            example:
              to: user@example.com
              subject: Welcome to our app
              body: <p>Thanks for signing up!</p>
      responses:
        '200':
          description: Email accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /track:
    post:
      operationId: trackEvent
      tags:
        - Events
      summary: Track a contact event
      description: >-
        Publishes a named event for a contact. If the contact does not exist it is
        created. Events trigger any matching automation. This endpoint may be called
        with either a public key (pk_) for safe client-side use or a secret key.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackEventRequest'
            example:
              event: signed-up
              email: user@example.com
              subscribed: true
              data:
                plan: pro
      responses:
        '200':
          description: Event recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackEventResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contacts:
    get:
      operationId: getContacts
      tags:
        - Contacts
      summary: List all contacts
      description: Returns every contact in the project.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A list of contacts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createContact
      tags:
        - Contacts
      summary: Create a contact
      description: >-
        Creates a new contact with an email address, an optional subscription
        state, and arbitrary metadata used for personalization and segmentation.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactRequest'
            example:
              email: user@example.com
              subscribed: true
              data:
                firstName: John
                plan: pro
      responses:
        '200':
          description: The created contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    put:
      operationId: updateContact
      tags:
        - Contacts
      summary: Update a contact
      description: Updates the subscription state and/or metadata of an existing contact.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContactRequest'
            example:
              id: contact_123
              data:
                plan: enterprise
      responses:
        '200':
          description: The updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteContact
      tags:
        - Contacts
      summary: Delete a contact
      description: Permanently deletes a contact by id.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  description: The id of the contact to delete.
            example:
              id: contact_123
      responses:
        '200':
          description: The deleted contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/{id}:
    get:
      operationId: getContact
      tags:
        - Contacts
      summary: Get a contact
      description: Retrieves a single contact by its id.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The id of the contact.
      responses:
        '200':
          description: The requested contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/count:
    get:
      operationId: getContactCount
      tags:
        - Contacts
      summary: Count contacts
      description: Returns the total number of contacts in the project.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: The contact count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    example: 4096
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contacts/subscribe:
    post:
      operationId: subscribeContact
      tags:
        - Contacts
      summary: Subscribe a contact
      description: Sets a contact's subscription state to subscribed.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactSubscriptionRequest'
            example:
              id: contact_123
      responses:
        '200':
          description: The updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/unsubscribe:
    post:
      operationId: unsubscribeContact
      tags:
        - Contacts
      summary: Unsubscribe a contact
      description: Sets a contact's subscription state to unsubscribed.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactSubscriptionRequest'
            example:
              id: contact_123
      responses:
        '200':
          description: The updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /campaigns:
    post:
      operationId: createCampaign
      tags:
        - Campaigns
      summary: Create a campaign
      description: >-
        Creates a one-off marketing campaign with a subject, HTML body, optional
        styling, and an explicit list of recipients.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCampaignRequest'
            example:
              subject: Product launch
              body: <p>We just shipped something new.</p>
              recipients:
                - user@example.com
              style: PLUNK
      responses:
        '200':
          description: The created campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
    put:
      operationId: updateCampaign
      tags:
        - Campaigns
      summary: Update a campaign
      description: Updates an existing draft campaign.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCampaignRequest'
      responses:
        '200':
          description: The updated campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCampaign
      tags:
        - Campaigns
      summary: Delete a campaign
      description: Deletes a campaign by id.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
            example:
              id: campaign_123
      responses:
        '200':
          description: The deleted campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /campaigns/send:
    post:
      operationId: sendCampaign
      tags:
        - Campaigns
      summary: Send a campaign
      description: Delivers a previously created campaign to its recipients, optionally at a scheduled time.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendCampaignRequest'
            example:
              id: campaign_123
              live: true
      responses:
        '200':
          description: The campaign that was sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Plunk API key passed as a Bearer token. Use a secret key (sk_) for most
        endpoints; the /track endpoint additionally accepts a public key (pk_).
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request body failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests; the project rate limit was exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    SendEmailRequest:
      type: object
      required:
        - to
        - subject
        - body
      properties:
        to:
          description: Recipient email address, or an array of addresses.
          oneOf:
            - type: string
              format: email
            - type: array
              items:
                type: string
                format: email
        subject:
          type: string
          description: Email subject line.
        body:
          type: string
          description: Email body, as HTML or plain text.
        subscribed:
          type: boolean
          description: Whether the recipient is treated as a subscribed contact.
        name:
          type: string
          description: Display name to send from.
        from:
          type: string
          format: email
          description: Sender email address (must be a verified sender).
        reply:
          type: string
          format: email
          description: Reply-to email address.
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom email headers.
        attachments:
          type: array
          description: File attachments.
          items:
            type: object
            properties:
              filename:
                type: string
              content:
                type: string
                description: Base64-encoded file content.
              type:
                type: string
                description: MIME type of the attachment.
    SendEmailResponse:
      type: object
      properties:
        success:
          type: boolean
        emails:
          type: array
          items:
            type: object
            properties:
              contact:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string
              email:
                type: string
        timestamp:
          type: string
          format: date-time
    TrackEventRequest:
      type: object
      required:
        - event
        - email
      properties:
        event:
          type: string
          description: The name of the event (e.g. "signed-up").
        email:
          type: string
          format: email
          description: The contact's email address.
        subscribed:
          type: boolean
          description: Sets the subscription state of the contact.
        data:
          type: object
          additionalProperties: true
          description: Arbitrary metadata stored on the contact.
    TrackEventResponse:
      type: object
      properties:
        success:
          type: boolean
        contact:
          type: string
          description: The id of the contact.
        event:
          type: string
          description: The id of the recorded event.
        timestamp:
          type: string
          format: date-time
    Contact:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        subscribed:
          type: boolean
        data:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateContactRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
        subscribed:
          type: boolean
          default: true
        data:
          type: object
          additionalProperties: true
    UpdateContactRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        subscribed:
          type: boolean
        data:
          type: object
          additionalProperties: true
    ContactSubscriptionRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: The id of the contact.
    Campaign:
      type: object
      properties:
        id:
          type: string
        subject:
          type: string
        body:
          type: string
        status:
          type: string
          enum:
            - DRAFT
            - SENT
        style:
          type: string
        recipients:
          type: array
          items:
            type: string
        projectId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateCampaignRequest:
      type: object
      required:
        - subject
        - body
        - recipients
      properties:
        subject:
          type: string
        body:
          type: string
        recipients:
          type: array
          items:
            type: string
            format: email
        style:
          type: string
          description: Email styling preset (e.g. PLUNK or HTML).
          enum:
            - PLUNK
            - HTML
    UpdateCampaignRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        subject:
          type: string
        body:
          type: string
        recipients:
          type: array
          items:
            type: string
            format: email
        style:
          type: string
    SendCampaignRequest:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: The id of the campaign to send.
        live:
          type: boolean
          description: When true the campaign is sent for real; when false a test send is performed.
        delay:
          type: integer
          description: Optional delay in minutes before sending.
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: integer
        error:
          type: string
        message:
          type: string
        time:
          type: integer