> ## Documentation Index
> Fetch the complete documentation index at: https://docs.migma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Klaviyo template

> Create an HTML template in the brand's connected Klaviyo account from a Migma email. Migma images are copied into the account's image library and the template links the copies; an image Klaviyo does not take keeps its Migma address and is listed under `images.kept` with the reason. Countdown timers and images on other sites stay as they are. Use this when the email should live in Klaviyo: the download from `GET /v1/export/klaviyo/{conversationId}` keeps images on Migma.

The brand is the conversation's brand, and its owner must have connected Klaviyo in Migma. Needs the `email:read` and `campaign:write` scopes, a paid plan, and permission to publish the brand's emails. An `Idempotency-Key` header is required: send the same key when retrying, so a retry returns the first template instead of creating another. A server error is not stored for replay, so after a 5xx check the account's templates before retrying.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/export/klaviyo/{conversationId}/push
openapi: 3.1.0
info:
  title: Migma.ai API (v1)
  description: >-
    API for managing brands, contacts, email generation, sending, and
    integrations. API request budgets are plan-based and shared across an
    account's API keys per route group. Sending request allowances support the
    account's recipients/second rate; recipient throughput and daily/monthly
    email quotas remain separate. See
    https://docs.migma.ai/api-reference/introduction#rate-limiting for limits,
    response headers, and retry behavior.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.migma.ai
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Projects/Brands
    description: Manage projects (brands) and import from websites
  - name: Contacts
    description: Manage your contacts, segments, tags, and topics
  - name: Segments
    description: Create and manage dynamic contact segments
  - name: Tags
    description: Organize contacts with tags
  - name: Topics
    description: Manage subscription topics and preferences
  - name: Emails
    description: Generate, send, and export emails
  - name: Email Validation
    description: Validate email content for compatibility and deliverability
  - name: Email Previews
    description: Preview emails across devices and email clients
  - name: Domains
    description: Manage sending domains and verification
  - name: Webhooks
    description: Manage webhook endpoints for real-time event notifications
  - name: Events
    description: Record customer events and conversions
  - name: Integrations
    description: Third-party platform integrations
  - name: Campaigns
    description: Create, schedule, send, and manage email campaigns
  - name: Billing
    description: View your plan and credits and create billing links
  - name: Project Editing
    description: Edit project assets, logos, images, and knowledge base entries
paths:
  /v1/export/klaviyo/{conversationId}/push:
    post:
      tags:
        - Emails
      summary: Create Klaviyo template
      description: >-
        Create an HTML template in the brand's connected Klaviyo account from a
        Migma email. Migma images are copied into the account's image library
        and the template links the copies; an image Klaviyo does not take keeps
        its Migma address and is listed under `images.kept` with the reason.
        Countdown timers and images on other sites stay as they are. Use this
        when the email should live in Klaviyo: the download from `GET
        /v1/export/klaviyo/{conversationId}` keeps images on Migma.


        The brand is the conversation's brand, and its owner must have connected
        Klaviyo in Migma. Needs the `email:read` and `campaign:write` scopes, a
        paid plan, and permission to publish the brand's emails. An
        `Idempotency-Key` header is required: send the same key when retrying,
        so a retry returns the first template instead of creating another. A
        server error is not stored for replay, so after a 5xx check the
        account's templates before retrying.
      operationId: PushKlaviyoTemplate
      parameters:
        - name: conversationId
          in: path
          required: true
          description: The conversation whose email is pushed
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Required key of at most 100 characters. Same key and same body
            within 24 hours replays the created template, so no second one is
            made; same key with a different body after a success returns 409
            IDEMPOTENCY_CONFLICT. Refusals are not stored, so after connecting
            Klaviyo or choosing an account, retry with the same key. Scoped per
            API key. Use a new key for a new template.
          schema:
            type: string
            maxLength: 100
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                emailId:
                  type: string
                  pattern: ^[0-9a-fA-F]{24}$
                  description: >-
                    One email of a series in this conversation. Omitted: the
                    conversation's latest email, as the download exports.
                connectionId:
                  type: string
                  pattern: ^[0-9a-fA-F]{24}$
                  description: >-
                    Which of the brand's Klaviyo accounts to use. Required only
                    when the brand has several; the 400
                    INTEGRATION_ACCOUNT_REQUIRED error lists them.
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Template name in Klaviyo. Defaults to the email's title.
            example:
              name: Spring sale
      responses:
        '201':
          description: Template created in Klaviyo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseKlaviyoTemplatePush'
        '400':
          description: >-
            Invalid body (every bad field is named), missing Idempotency-Key
            (IDEMPOTENCY_KEY_REQUIRED), or several Klaviyo accounts and no
            connectionId (INTEGRATION_ACCOUNT_REQUIRED, with `data.accounts`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Missing scope, no permission to publish this brand's emails, or a
            free plan (code UPGRADE_REQUIRED, with the pricing link in the
            message)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            Klaviyo is not connected to this brand (KLAVIYO_NOT_CONNECTED), or
            Klaviyo refused the connection's access
            (KLAVIYO_RECONNECT_REQUIRED); both carry `data.connectUrl` and the
            link in the message. Also returned when the Idempotency-Key was
            reused with a different body after a success (IDEMPOTENCY_CONFLICT).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: >-
            The connectionId is not one of the brand's Klaviyo accounts
            (KLAVIYO_ACCOUNT_NOT_FOUND, with `data.accounts`), or the email has
            no content yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: >-
            A request with this Idempotency-Key is still running
            (IDEMPOTENCY_IN_PROGRESS). Retry with the same key after the
            Retry-After delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-codeSamples:
        - lang: javascript
          label: Node.js SDK
          source: >-
            import { Migma } from 'migma';


            const migma = new Migma('YOUR_API_KEY');


            const { data, error } = await migma.export.pushToKlaviyo(
              'CONVERSATION_ID',
              { name: 'Spring sale' },
              { idempotencyKey: 'push-spring-sale-1' }
            );

            // data.editorUrl opens the template in Klaviyo; data.images.kept
            lists images still on Migma.
components:
  schemas:
    ApiResponseKlaviyoTemplatePush:
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/KlaviyoTemplatePush'
    ApiError:
      type: object
      properties:
        success:
          type: boolean
          default: false
        error:
          type: string
        code:
          type: string
          description: >-
            Machine-readable error code (e.g., IDEMPOTENCY_CONFLICT,
            DOMAIN_CLAIMABLE, UPGRADE_REQUIRED, APPROVED_SEND_LOCKED).
        data:
          type: object
          description: >-
            Additional structured context for the error, such as the affected
            domain.
          additionalProperties: true
      required:
        - success
        - error
    ApiResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          nullable: true
        error:
          type: string
          nullable: true
      required:
        - success
    KlaviyoTemplatePush:
      type: object
      required:
        - templateId
        - name
        - editorUrl
        - connectionId
        - images
      properties:
        templateId:
          type: string
          description: The template's id in Klaviyo
        name:
          type: string
        editorUrl:
          type: string
          format: uri
          description: Opens the template in Klaviyo's editor
        connectionId:
          type: string
          description: The Klaviyo account the template was created in
        images:
          type: object
          required:
            - hosted
            - kept
          properties:
            hosted:
              type: integer
              description: Images now served from Klaviyo's image library
            kept:
              type: array
              description: Images still linked from Migma, with the reason
              items:
                type: object
                required:
                  - url
                  - reason
                properties:
                  url:
                    type: string
                  reason:
                    type: string
      example:
        templateId: WJ3kbV
        name: Spring sale
        editorUrl: https://www.klaviyo.com/email-editor/WJ3kbV/edit
        connectionId: 6735f0c2a1b2c3d4e5f60718
        images:
          hosted: 4
          kept: []
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key authentication. Use 'Authorization: Bearer YOUR_API_KEY' where
        YOUR_API_KEY is obtained from the Migma dashboard under Settings →
        Developers → API Keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.