slideforge-dev Email API

openapi: 3.2.0
info:
  title: SlideForge Email API
  description: 'Agent-first PowerPoint generation. Send structured slide intents (a `form` plus typed fields) or a brief; get back a real, editable `.pptx`. The draw path is deterministic — no model renders your slide, so supplied numbers and text come out verbatim. Every response carries `status`, `fidelity` and `warnings` so an automated caller can tell whether the output is usable. $0.05 per slide; an unusable slide is not billed. Authenticate with a SlideForge API key (`Authorization: Bearer sf_live_…` or `X-API-Key`) — new accounts include 60 free slides, no credit card: https://slideforge.dev/sign-up'
  version: 5.356.0
servers:
- url: https://api.slideforge.dev
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Email
paths:
  /v1/email/unsubscribe:
    post:
      tags:
      - Email
      summary: Unsubscribe One Click
      description: 'RFC 8058 one-click. The mail client posts here with no human present.


        The token travels in the query string — that is what the List-Unsubscribe header carries.

        The POST body is the fixed `List-Unsubscribe=One-Click` and is not read.'
      operationId: unsubscribe_one_click_v1_email_unsubscribe_post
      parameters:
      - name: t
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: T
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Email
      summary: Unsubscribe Link
      description: The link in the body, clicked by a person.
      operationId: unsubscribe_link_v1_email_unsubscribe_get
      parameters:
      - name: t
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: T
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/email/clicked:
    post:
      tags:
      - Email
      summary: Record Click
      description: 'Stamp the first click on a campaign mail. Called by the web middleware, not a person.


        Campaign links are ordinary slideforge.dev URLs carrying `?src=&sid=`; Resend''s own click

        tracking, which would rewrite every link through a tracking subdomain, stays off. So the

        click reaches us the same way any other visit does and this endpoint is what turns a

        landing into an attributed click.


        Unauthenticated for the same reason unsubscribe is: the reader has usually not logged in

        yet — /console/billing, where the top-up mails point, bounces them through Auth0 first.

        A `sid` grants nothing; the only effect it can have is setting one timestamp on the row

        it names, once.


        Silent on an unknown id. The middleware fires this without waiting for the answer, so a

        404 would be read by nobody and would only tell a prober which ids exist.'
      operationId: record_click_v1_email_clicked_post
      parameters:
      - name: sid
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Sid
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'SlideForge API key: `Authorization: Bearer sf_live_…`. Create one at https://slideforge.dev/console/keys'
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Same key, header form — for clients that cannot set Authorization.