Inflection.io Email Versions API

openapi: 3.2.0
info:
  title: Inflection Developer Email Versions API
  version: 1.0.0
  description: 'The Inflection Developer API (`/v2`). Authenticate with a Personal Access

    Token (`Authorization: Bearer inf_pat_...`).


    **`/v2` is `/v1` plus more.** Every `/v1` endpoint is served here unchanged,

    so a client can pin to one version and reach the whole API. On top of those

    sit reads `/v1` never had: journeys, journey and email stats with a journey

    rollup, and the email and list collections. `/v1` remains published.


    **Response envelope.** Every response is wrapped:

    `{ "data": …, "pagination": …, "errors": [...], "meta": { "status": "SUCCESS|FAILURE", "timestamp": "…" } }`.

    `data` carries the payload, `pagination` appears only on paged lists, and on

    failures `errors` is populated with `meta.status: "FAILURE"`.


    **Query parameters are camelCase**: `pageNumber`, `pageSize`, `startTime`,

    `folderId`. The journeys, emails, lists and stats reads additionally accept

    the snake_case spelling of every scalar parameter (`page_number`,

    `folder_id`, …); the contact, activity and list-member endpoints do not.

    Repeatable parameters also accept a `[]` suffix (`status[]`, `tag[]`).


    **Asynchronous contact writes.** `POST/PATCH /v2/contacts*` are processed

    asynchronously: they return **200** with a `PENDING` transaction

    acknowledgement (not the created/updated contact). Poll

    `GET /v2/contacts/transactions/{transactionId}` for the per-contact result.


    **Status-code quirks** (documented per-operation): a missing **contact** is

    reported as **400** (not 404), whereas a missing **list**, **email** or

    **journey** is **404**. For journeys and emails that also covers a

    soft-deleted record and a malformed id. Nothing returns 201 or 204.


    **Empty results are not errors.** On the paged reads, a `tag`, `folderId` or

    `search` that matches nothing returns an empty page, not a 404.


    **Errors.** Failures use the envelope above

    (`errors[].{errorCode,message,detail}`). Authentication and authorization

    failures (401/403) are returned with an empty body. The journey stats rollup

    adds `RESULT_SET_TOO_LARGE` (a **400**) when a filter matches more journeys

    than one request may cover; narrow it rather than paging further.


    **Rate limiting.** Requests are metered per tenant. Exceeding the budget

    yields **429** (empty body) on any endpoint; the `Retry-After` header gives

    the seconds to wait and `X-RateLimit-Limit` the sustained per-second budget.'
servers:
- url: https://api.inflection.io
  description: Production
security:
- PatAuth: []
tags:
- name: Email Versions
  description: Per-contact versions of a Personalized Email Asset, served under `/v1`.
paths:
  /v1/email-versions:
    post:
      operationId: setEmailVersion
      summary: Set a personalized email version
      tags:
      - Email Versions
      description: 'Stores the personalized version of a Personalized Email Asset for one contact. One version per contact per asset; re-posting for the same contact replaces their version. At send time the contact receives their version if it''s ready; contacts without one get the asset''s default email.


        Validation on arrival: `email` must resolve to an existing contact, and `html` must contain the literal `{{unsubscribe_url}}` token, contain no other `{{…}}` tokens, and stay within 500 KB. A version that fails validation is rejected with a reason (visible on the asset''s **Activity** tab) and the default email sends instead.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - assetId
              - email
              - subject
              - preheader
              - html
              properties:
                assetId:
                  type: string
                  description: ID of the Personalized Email Asset. Copy it from the asset URL (`…/assets/email/per-user/<ASSET_ID>/versions`) or its **How to add versions** tab.
                email:
                  type: string
                  format: email
                  description: The contact's email. Must match an existing contact.
                subject:
                  type: string
                  description: The personalized subject line.
                preheader:
                  type: string
                  description: The inbox preview text.
                html:
                  type: string
                  description: Full HTML of the personalized email. Must include the literal `{{unsubscribe_url}}` token; no other `{{…}}` tokens are allowed. Max 500 KB.
                expiresAt:
                  type: string
                  format: date-time
                  description: Optional ISO-8601 expiry. After this moment the contact falls back to the default email. Omit for a version that never expires.
            example:
              assetId: 6a60ee387b78bbc9a263aba0
              email: contact@example.com
              subject: A note just for you
              preheader: Personalized for you
              html: <!doctype html>…<a href="{{unsubscribe_url}}">Unsubscribe</a>…
              expiresAt: '2030-01-01T00:00:00Z'
      responses:
        '200':
          description: Version stored.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        status:
                          type: string
                          example: stored
        '400':
          description: 'Validation failed: malformed JSON, unknown `assetId`, contact not found, missing `{{unsubscribe_url}}`, a disallowed `{{…}}` token, or HTML over 500 KB.'
        '401':
          description: Missing or malformed bearer token.
components:
  schemas:
    Envelope:
      type: object
      properties:
        data:
          description: 'Payload: object or array, shape depends on the endpoint.'
        pagination:
          type: object
          description: Present only on paged list endpoints.
          properties:
            pageNumber:
              type: integer
              example: 1
            pageSize:
              type: integer
              example: 20
            totalElements:
              type: integer
              example: 151
            totalPages:
              type: integer
              example: 8
        errors:
          type: array
          items:
            type: object
            properties:
              errorCode:
                type: string
              message:
                type: string
              detail:
                type: string
        meta:
          type: object
          properties:
            status:
              type: string
              enum:
              - SUCCESS
              - FAILURE
            timestamp:
              type: string
              format: date-time
  securitySchemes:
    PatAuth:
      type: http
      scheme: bearer
      bearerFormat: inf_pat
      description: 'Personal Access Token or OAuth 2.1 access token, sent as a bearer

        credential (`Authorization: Bearer inf_pat_...`). Read operations

        require a token with the `READ` scope; write operations

        (POST/PATCH/DELETE) require `WRITE`.

        '
x-provenance:
  method: harvested
  publisher: Inflection.io
  source: https://docs.inflection.io/api-reference/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)