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

# Enqueue contacts for bulk enrollment into a Reply.io sequence.

> Enqueue contacts for bulk enrollment into a Reply.io sequence.

    Buffers contacts in Redis (partitioned by sequence_id) and flushes every
    60s via Reply v3's true bulk endpoints: /v3/contacts/import (upsert) →
    /v3/sequences/{id}/contact-links/bulk (enroll).

    Use this instead of looping `reply_add_contact_to_sequence` when you have
    multiple contacts to enroll into the same sequence — it collapses N
    rate-limited v1 calls into 2 v3 calls per chunk of up to REPLY_BULK_MAX
    (default 100).

    Per-contact shape (email required, others optional):
      {
        "email":         "alex@example.com",
        "first_name":    "Alex",
        "last_name":     "Stone",
        "company":       "Example Inc",
        "title":         "VP Sales",
        "linkedin_url":  "https://linkedin.com/in/...",
        "phone":         "+1...",
        "custom_fields": {"campaign": "Q2 outbound", ...}
      }

    Dedupes by (sequence_id, email) within the intake AND against records
    already queued for the same sequence — first-seen wins.

    Returns {batch_id, accepted, queued, schema_errors:[...], dedupe_skips:[...]}.
    Poll reply_bulk_enroll_batch_status(batch_id) for per-contact outcomes
    once the flusher has processed them.



## OpenAPI

````yaml /openapi/private/specs/mcp/sagescreen.yml post /tools/reply_bulk_enroll_enqueue
openapi: 3.1.0
info:
  title: SageScreen — MCP Tool Catalog
  description: >-
    Agent-callable tools exposed by the SageScreen MCP server at
    `https://mcp.sagescreen.net`.


    These are the same tools served over the Model Context Protocol; this
    reference documents their **REST** surface (`POST /tools/{name}`, body = the
    tool's arguments), which is what the playground below invokes. The live,
    machine-readable catalog is `GET /tools/list`.


    **This page is generated deterministically** from the server's tool registry
    (`apps/docs/scripts/generate_mcp_spec.py`), not hand-written and not
    AI-generated — it cannot drift from the shipped tools.


    All calls authenticate with the `X-Service-Token` header (or `?token=`).
  version: 1.0.0
servers:
  - url: https://mcp.sagescreen.net
    description: Production MCP server
security:
  - serviceToken: []
  - tokenQuery: []
tags:
  - name: Agents
  - name: Contact Push
  - name: Image Generation
  - name: Other
  - name: Productlane
  - name: Reply.io
  - name: Sequences
  - name: Spaces
  - name: WordPress
paths:
  /tools/reply_bulk_enroll_enqueue:
    post:
      tags:
        - Reply.io
      summary: Enqueue contacts for bulk enrollment into a Reply.io sequence.
      description: |-
        Enqueue contacts for bulk enrollment into a Reply.io sequence.

            Buffers contacts in Redis (partitioned by sequence_id) and flushes every
            60s via Reply v3's true bulk endpoints: /v3/contacts/import (upsert) →
            /v3/sequences/{id}/contact-links/bulk (enroll).

            Use this instead of looping `reply_add_contact_to_sequence` when you have
            multiple contacts to enroll into the same sequence — it collapses N
            rate-limited v1 calls into 2 v3 calls per chunk of up to REPLY_BULK_MAX
            (default 100).

            Per-contact shape (email required, others optional):
              {
                "email":         "alex@example.com",
                "first_name":    "Alex",
                "last_name":     "Stone",
                "company":       "Example Inc",
                "title":         "VP Sales",
                "linkedin_url":  "https://linkedin.com/in/...",
                "phone":         "+1...",
                "custom_fields": {"campaign": "Q2 outbound", ...}
              }

            Dedupes by (sequence_id, email) within the intake AND against records
            already queued for the same sequence — first-seen wins.

            Returns {batch_id, accepted, queued, schema_errors:[...], dedupe_skips:[...]}.
            Poll reply_bulk_enroll_batch_status(batch_id) for per-contact outcomes
            once the flusher has processed them.
      operationId: reply_bulk_enroll_enqueue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                sequence_id:
                  title: Sequence Id
                  type: integer
                contacts:
                  items: {}
                  title: Contacts
                  type: array
              required:
                - sequence_id
                - contacts
              type: object
      responses:
        '200':
          description: >-
            Tool result. The shape is tool-specific; most tools return a JSON
            object, some a `{"result": ...}` envelope.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad arguments (unknown kwargs, malformed JSON body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown tool name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Tool raised an error during execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
        detail:
          type: string
          description: Optional additional context.
      required:
        - error
  responses:
    Unauthorized:
      description: Missing or invalid service token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unauthorized
  securitySchemes:
    serviceToken:
      type: apiKey
      in: header
      name: X-Service-Token
    tokenQuery:
      type: apiKey
      in: query
      name: token

````