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

# Queue outbound email(s) from your Agent

> Queue email Tasks for an email-enabled agent account. Pass target or to/cc/bcc for one email, or use up to 10,000 targets for separate emails. Organization default goals and retries apply when configured; use POST /api/v2/tasks to supply a Task-specific goal or retry policy. Submissions over 1,000 targets require Idempotency-Key and return 202. Use meta.contact for structured Contact data such as name, email, address and customFields. In a batch, put lead-specific metadata on each target object. See [Contact fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields) for the complete metadata field reference.



## OpenAPI

````yaml post /api/v2/agent/outboundEmail
openapi: 3.0.0
info:
  version: 2.0.0
  title: Vida API
  description: Vida API Documentation
servers:
  - url: https://api.vida.dev
    description: Vida Production
    variables:
      baseUrl:
        default: api.vida.dev
        description: Production API Root
security: []
tags:
  - name: Agents
  - name: Apps
    description: Install Vida apps and use their enabled integration functions.
  - name: Integrations
    description: Configure Vader integrations.
  - name: Inbound Email
    description: Control which senders may create inbound email work for an Agent.
  - name: Features
    description: Inspect capabilities available within an account hierarchy.
  - name: Conversation Logs
    description: Query conversation activity and calculate account-level metrics.
  - name: Computer Agents
    description: Set up, configure, inspect, and manage Vida Computer Agents.
  - name: Computer Agent Sessions
    description: View and reset Computer Agent sessions.
  - name: Accounts
  - name: Agent Templates
    description: Create, manage, and apply reusable Agent configurations.
paths:
  /api/v2/agent/outboundEmail:
    post:
      tags:
        - Agents
      summary: Queue outbound email(s) from your Agent
      description: >-
        Queue email Tasks for an email-enabled agent account. Pass target or
        to/cc/bcc for one email, or use up to 10,000 targets for separate
        emails. Organization default goals and retries apply when configured;
        use POST /api/v2/tasks to supply a Task-specific goal or retry policy.
        Submissions over 1,000 targets require Idempotency-Key and return 202.
        Use meta.contact for structured Contact data such as name, email,
        address and customFields. In a batch, put lead-specific metadata on each
        target object. See [Contact
        fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields)
        for the complete metadata field reference.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: object
            properties:
              type:
                type: string
                example: string
              maxLength:
                type: number
                example: 200
          description: >-
            Required for submissions over 1,000 targets. Repeating the same key
            and payload safely resumes or returns that submission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              oneOf:
                - type: object
                  required:
                    - content
                  properties:
                    target:
                      type: string
                      description: Destination email address
                      example: person@example.com
                    to:
                      description: >-
                        Destination email address or array of destination email
                        addresses for one email
                    cc:
                      description: >-
                        CC email address or array of CC email addresses for one
                        email
                    bcc:
                      description: >-
                        BCC email address or array of BCC email addresses for
                        one email
                    content:
                      type: string
                      description: Email body. Raw HTML is supported.
                    subject:
                      type: string
                      description: Email subject line
                    attachments:
                      type: array
                      description: SendGrid-style attachment objects with base64 content
                    context:
                      type: string
                      description: Optional context for the task
                    taskContext:
                      type: string
                      description: Task-specific context
                    accountId:
                      type: integer
                      description: Optional agent account id override
                    agentId:
                      type: integer
                      description: Optional campaign id override
                    roomId:
                      type: string
                      description: Room id when replying to an existing email message
                    replyToMessageUuid:
                      type: string
                      description: >-
                        Email message uuid to reply to; used with roomId for
                        thread headers
                    scheduledFor:
                      type: integer
                      description: Unix seconds to schedule delivery
                    meta:
                      type: object
                      additionalProperties: true
                      properties:
                        contact:
                          $ref: '#/components/schemas/TaskContactFields'
                      description: >-
                        Optional Task metadata. meta.contact fills missing
                        structured Contact fields at creation; existing values
                        are preserved. For multiple targets, set contact data in
                        meta.contact on each target object. Per-item meta
                        replaces the entire top-level meta object; it is not
                        deep-merged.
                    externalTaskId:
                      type: string
                      description: >-
                        Reusable customer correlation/grouping ID; not an
                        idempotency key
                    contactListName:
                      type: string
                      description: Optional Contact List to enroll the contact into
                - type: object
                  required:
                    - targets
                  properties:
                    targets:
                      description: >-
                        Email addresses or per-recipient objects. Supply
                        distinct meta.contact data per lead.
                      oneOf:
                        - type: array
                          items:
                            type: string
                        - type: array
                          items:
                            type: object
                            required:
                              - target
                            properties:
                              target:
                                type: string
                              content:
                                type: string
                              subject:
                                type: string
                              meta:
                                type: object
                                additionalProperties: true
                                properties:
                                  contact:
                                    $ref: '#/components/schemas/TaskContactFields'
                                description: >-
                                  Per-recipient metadata replaces the entire
                                  top-level meta object.
                    content:
                      type: string
                      description: Email body applied to string targets
                    subject:
                      type: string
                      description: Subject applied to string targets
                    cc:
                      description: CC applied to string targets
                    bcc:
                      description: BCC applied to string targets
                    attachments:
                      type: array
                      description: Attachments applied to string targets
                    context:
                      type: string
                    taskContext:
                      type: string
                    accountId:
                      type: integer
                    agentId:
                      type: integer
                    scheduledFor:
                      type: integer
                    scheduleSpacingSec:
                      type: integer
                      description: >-
                        If provided, stagger scheduledFor by this many seconds
                        per index
                    meta:
                      type: object
                      additionalProperties: true
                      properties:
                        contact:
                          $ref: '#/components/schemas/TaskContactFields'
                      description: >-
                        Optional Task metadata. meta.contact fills missing
                        structured Contact fields at creation; existing values
                        are preserved. For multiple targets, set contact data in
                        meta.contact on each target object. Per-item meta
                        replaces the entire top-level meta object; it is not
                        deep-merged.
                    externalTaskId:
                      type: string
                      description: >-
                        Reusable correlation/grouping ID applied to all created
                        Tasks
                    contactListName:
                      type: string
                      description: Contact List to enroll every contact into
            examples:
              single:
                summary: Email a lead and populate their Contact
                value:
                  target: lead@example.com
                  subject: Your requested information
                  content: Here is the information you requested.
                  meta:
                    contact:
                      name: Example Person
                      phone: '+15551234567'
                      address:
                        state: LA
                        zip: '71101'
                      customFields:
                        vendorLeadCode: lead-123
      responses:
        '200':
          description: Queued successfully
        '202':
          description: Large email Task submission accepted for asynchronous creation
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Server Error
      security:
        - apiKeyAuth: []
components:
  schemas:
    TaskContactFields:
      type: object
      additionalProperties: false
      description: >-
        Optional Contact fields for call, text and email Task creation,
        including outboundCall, outboundSms and outboundEmail. Fills missing
        fields on the target Contact in the Task organization before scheduling.
        Nested objects fill missing leaves; existing nonblank values, false,
        zero and nonempty arrays are preserved. Strings are trimmed; null, blank
        strings and empty objects/arrays are ignored. New Contacts use the
        supplied name instead of a global-profile default. Existing target
        phone/email defaults remain canonical. Does not change the Task target,
        global user profile or outbound caller ID. Task updates do not apply
        Contact changes; use the Contact API to replace or clear existing
        values. Identity and ownership fields are not accepted. See [Contact
        fields](https://vida.io/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields)
        for the full field reference.
      properties:
        name:
          type: string
          nullable: true
          example: Example Person
        title:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
          example: lead@example.com
        phone:
          type: string
          nullable: true
          example: '+15551234567'
        cnam:
          type: string
          nullable: true
          description: >-
            Organization Contact display data only; does not change outbound
            caller ID.
        mobile:
          type: string
          nullable: true
        birthday:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        image:
          type: string
          nullable: true
        address:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            street:
              type: string
              nullable: true
            city:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            zip:
              type: string
              nullable: true
              example: '07101'
            country:
              type: string
              nullable: true
        company:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            name:
              type: string
              nullable: true
            industry:
              type: string
              nullable: true
            position:
              type: string
              nullable: true
            website:
              type: string
              nullable: true
            address:
              type: string
              nullable: true
        preferredContactMethod:
          type: string
          nullable: true
        marketingOptIn:
          type: boolean
          nullable: true
        contactSource:
          type: string
          nullable: true
        socialMedia:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            linkedin:
              type: string
              nullable: true
            twitter:
              type: string
              nullable: true
            facebook:
              type: string
              nullable: true
            instagram:
              type: string
              nullable: true
        leadSource:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        tags:
          type: array
          nullable: true
          items:
            type: string
        notes:
          type: string
          nullable: true
        agentContext:
          type: string
          nullable: true
        customFields:
          type: object
          nullable: true
          additionalProperties: true
          maxProperties: 20
          description: >-
            Custom JSON data, at most 20 top-level keys and 8192 UTF-8 JSON
            bytes, including existing values after merge.
          example:
            vendorLeadCode: lead-123
            source: website
        lastTask:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            taskId:
              oneOf:
                - type: string
                - type: number
              nullable: true
            listId:
              oneOf:
                - type: string
                - type: number
              nullable: true
            timestamp:
              type: number
              nullable: true
            success:
              type: boolean
              nullable: true
        lists:
          type: array
          nullable: true
          items:
            type: object
            required:
              - label
            properties:
              label:
                type: string
              timestamp:
                type: number
        appointments:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: token
      description: Vida API Token

````