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

# Patch email

> Requires one of the following scopes: `emails:update`, `emails:all`, `all:update`, `all:all`



## OpenAPI

````yaml https://api.instantly.ai/openapi/api_v2.json patch /api/v2/emails/{id}
openapi: 3.1.0
info:
  title: API Explorer
  description: >-
    The entire API V2 documentation is interactive and can be tested here. To
    the right side of every endpoint you will see a box with an example request.
    You can click on the "Try it" button to send a request to the server right
    from the docs. You will need to provide an API key by clicking the
    `ApiKeyAuth_token` blue text.
  version: 2.0.0
servers:
  - url: https://api.instantly.ai
    description: Instantly API Server
security:
  - ApiKeyAuth: []
tags:
  - name: Analytics
    description: Endpoints related to analytics
    x-displayName: Analytics
  - name: OAuth
    description: >-
      OAuth authentication endpoints for connecting Google and Microsoft email
      accounts
    x-displayName: OAuth
  - name: Account
    description: An email account that can be used to send campaigns
    x-displayName: Account
  - name: Campaign
    description: A campaign that can be sent to a list of recipients
    x-displayName: Campaign
  - name: Email
    description: >-
      A campaign email, a reply, a manually sent email, or any other email
      that's visible in the Unibox
    x-displayName: Email
  - name: EmailVerification
    description: A single email verification
    x-displayName: Email Verification
  - name: LeadList
    description: A list used to store leads
    x-displayName: Lead List
  - name: InboxPlacementTest
    description: An inbox placement test
    x-displayName: Inbox Placement Test
  - name: InboxPlacementAnalytics
    description: Analytics data for individual emails in inbox placement tests
    x-displayName: Inbox Placement Analytics
  - name: InboxPlacementBlacklist&SpamAssassinReport
    description: Report data for an inbox placement test
    x-displayName: Inbox Placement Blacklist & SpamAssassin Report
  - name: APIKey
    description: API Key
    x-displayName: API Key
  - name: AccountCampaignMapping
    description: Account Campaign Mapping
    x-displayName: Account Campaign Mapping
  - name: Lead
    description: A lead entity representing an individual lead
    x-displayName: Lead
  - name: BackgroundJob
    description: A background job that can be used to perform long-running tasks
    x-displayName: Background Job
  - name: CustomTag
    description: >-
      A custom tag for organizing and categorizing accounts and campaigns. You
      can use them as filters in apis that list accounts and campaigns.
    x-displayName: Custom Tag
  - name: CustomTagMapping
    description: >-
      This entity represents a tag being assigned to a specific campaign or
      email account. When an email account is assigned a tag, a new custom tag
      mapping entry is created, which connects the tag (`tag_id` field) with the
      email account (`resource_id` field). You can use it to see which tag si
      connected to which resource.
    x-displayName: Custom Tag Mapping
  - name: BlockListEntry
    description: A blocked email or domain
    x-displayName: Block List Entry
  - name: LeadLabel
    description: A custom label for categorizing and managing leads
    x-displayName: Lead Label
  - name: Workspace
    description: A workspace entity representing a workspace
    x-displayName: Workspace
  - name: SuperSearchEnrichment
    description: >-
      An enrichment can take different forms, such as email enrichment or
      LinkedIn enrichment. Leads may be imported from SuperSearch using the
      dedicated endpoint, or enriched directly within a list or campaign by
      attaching an enrichment to it.
    x-displayName: SuperSearch Enrichment
  - name: WorkspaceGroupMember
    description: >-
      A member of a workspace group. You can use the endpoints within this
      entity to manage the members of a workspace group.
    x-displayName: Workspace Group Member
  - name: WorkspaceMember
    description: A member of a workspace with associated user details
    x-displayName: Workspace Member
  - name: CampaignSubsequence
    description: A subsequence entity representing a follow-up sequence
    x-displayName: Campaign Subsequence
  - name: AuditLog
    description: Audit log records for tracking system activities
    x-displayName: Audit Log
  - name: Webhook
    description: A webhook subscription for receiving event notifications
    x-displayName: Webhook
  - name: WebhookEvent
    description: A webhook event that was sent or attempted to be sent
    x-displayName: Webhook Event
  - name: DFYEmailAccountOrder
    description: A Done-For-You email account order
    x-displayName: DFY Email Account Order
  - name: CustomPromptTemplate
    description: Custom prompt templates for creating custom prompts
    x-displayName: Custom Prompt Template
  - name: SalesFlow
    description: >-
      Manages how sales users view and interact with campaign and lead lists
      within the sales flow.
    x-displayName: Sales Flow
  - name: EmailTemplate
    description: A campaign email template
    x-displayName: Email Template
  - name: WorkspaceBilling
    description: Workspace Billing
    x-displayName: Workspace Billing
  - name: CRMActions
    description: CRM related actions
    x-displayName: CRM Actions
paths:
  /api/v2/emails/{id}:
    patch:
      tags:
        - Email
      summary: Patch email
      description: >-
        Requires one of the following scopes: `emails:update`, `emails:all`,
        `all:update`, `all:all`
      operationId: patchEmail
      parameters:
        - schema:
            type: string
            format: uuid
            example: 019e0e3e-b601-7f49-9708-1aec2bb2f893
          in: path
          name: id
          required: true
          description: The ID of the item to update
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                is_unread:
                  type:
                    - number
                    - 'null'
                  description: Indicates if the email is unread
                  example: 1
                reminder_ts:
                  type:
                    - string
                    - 'null'
                  description: Timestamp for the reminder.
                  format: date-time
                  example: '2026-05-09T19:37:14.294Z'
              required: []
              additionalProperties: false
              minProperties: 1
      responses:
        '200':
          description: The updated Email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/def-2'
        '401':
          description: >-
            This request is unauthorized (either the Authorization header is
            missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 401
                    example: 401
                  error:
                    type: string
                    enum:
                      - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    example: Missing Authorization header
                required:
                  - statusCode
                  - error
                  - message
        '402':
          description: >-
            This request cannot be fulfilled because the workspace does not have
            an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 402
                    example: 402
                  error:
                    type: string
                    enum:
                      - Payment Required
                    example: Payment Required
                  message:
                    type: string
                    example: Workspace does not have an active paid plan
                required:
                  - statusCode
                  - error
                  - message
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 404
                    example: 404
                  error:
                    type: string
                    enum:
                      - Not Found
                    example: Not Found
                  message:
                    type: string
                    example: Resource not found
                required:
                  - statusCode
                  - error
                  - message
        '429':
          description: >-
            You have exceeded the rate limit. Please check the rate limit docs
            for more information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 429
                    example: 429
                  error:
                    type: string
                    enum:
                      - Too Many Requests
                    example: Too Many Requests
                  message:
                    type: string
                    example: Rate limit exceeded
                required:
                  - statusCode
                  - error
                  - message
components:
  schemas:
    def-2:
      title: Email
      description: >-
        A campaign email, a reply, a manually sent email, or any other email
        that's visible in the Unibox
      x-tags:
        - Schemas
        - Email
      type: object
      properties:
        id:
          type: string
          description: A Unique identifier
          readOnly: true
          format: uuid
          example: 019e0e3e-7336-7063-ac55-c8390d8da4be
        timestamp_created:
          type: string
          description: >-
            Timestamp when the email was added to our database. This is not the
            timestamp of the email itself, since the email could have been sent
            at a different time. Please check the `timestamp_email` field for
            the timestamp of the email.
          readOnly: true
          format: date-time
          example: '2026-05-09T19:37:14.294Z'
        timestamp_email:
          type: string
          description: >-
            The timestamp of the email, as provided by the email server. Please
            note that the timestamp is not always accurate, as it can be
            manipulated by the sender or the email server.
          readOnly: true
          format: date-time
          example: '2026-05-09T19:37:14.294Z'
        message_id:
          type: string
          description: Unique email ID from the email server
          readOnly: true
          example: <example123@mail.gmail.com>
        subject:
          type: string
          description: Subject line of the email message
          example: 'Re: Your inquiry'
        from_address_email:
          type:
            - 'null'
            - string
          description: The sender email address, populated based on the eaccount
          readOnly: true
          format: email
          example: sender@example.com
        to_address_email_list:
          type: string
          description: Comma-separated list of recipient email addresses
          example: recipient@example.com
        cc_address_email_list:
          type:
            - 'null'
            - string
          description: Comma-separated list of CC email addresses
          example: cc@example.com
        bcc_address_email_list:
          type:
            - 'null'
            - string
          description: Comma-separated list of BCC email addresses
          example: bcc@example.com
        reply_to:
          type:
            - 'null'
            - string
          description: Reply-to email address
          example: replyto@example.com
        body:
          type: object
          description: An object containing the email body in HTML and text format
          readOnly: true
          properties:
            text:
              type: string
              description: Text content of the email
              example: This is a test email
            html:
              type: string
              description: HTML content of the email
              example: <p>This is a test email</p>
        organization_id:
          type: string
          description: The workspace ID
          readOnly: true
          format: uuid
          example: 019e0e3e-7336-7063-ac55-c83acbf31981
        campaign_id:
          type:
            - 'null'
            - string
          description: >-
            The id of the campaign that the email is associated with (it can be
            null for manually sent emails)
          format: uuid
          example: 019e0e3e-7336-7063-ac55-c83b3c357df8
        subsequence_id:
          type:
            - 'null'
            - string
          description: >-
            The id of the campaign subsequence that the email is associated with
            (it can be null for manually sent emails)
          format: uuid
          example: 019e0e3e-7336-7063-ac55-c83c3aafc66e
        list_id:
          type:
            - 'null'
            - string
          description: The id of the list (if the lead is part of a list)
          format: uuid
          example: 019e0e3e-7336-7063-ac55-c83d2d7842ef
        lead:
          type:
            - 'null'
            - string
          description: The email address of the lead that the email is associated with
          example: jondoe@example.com
        lead_id:
          type:
            - 'null'
            - string
          description: The lead id (if any)
          format: uuid
          example: 019e0e3e-7336-7063-ac55-c83e9600a5d2
        eaccount:
          type: string
          description: >-
            The email account that was used to send the email. This needs to be
            validated to make sure it exists in the user workspace
          example: eaccount-123
        ue_type:
          type:
            - 'null'
            - number
          description: Email type based on the life cycle of the email
          enum:
            - 1
            - 2
            - 3
            - 4
          x-enumDescriptions:
            '1': Sent from campaign
            '2': Received
            '3': Sent
            '4': Scheduled
          example: 3
        step:
          type:
            - 'null'
            - string
          description: The campaign step that the email is associated with
          example: step-123
        is_unread:
          type:
            - 'null'
            - number
          description: Indicates if the email is unread
          example: 1
        is_auto_reply:
          type:
            - 'null'
            - number
          description: >-
            Indicates if the email is an auto-reply. 0 (zero) - is false, and 1
            is true
          readOnly: true
          example: 0
        reminder_ts:
          type:
            - 'null'
            - string
          description: Timestamp for the reminder.
          format: date-time
          example: '2026-05-09T19:37:14.294Z'
        ai_interest_value:
          type:
            - 'null'
            - number
          description: AI interest value
          example: 0.75
        ai_assisted:
          type:
            - 'null'
            - number
          description: Indicates if AI assistance was used
          example: 1
        is_focused:
          type:
            - 'null'
            - number
          description: >-
            Indicates if the email is focused (is in the primary tab in the
            Unibox)
          example: 1
        i_status:
          type:
            - 'null'
            - number
          description: Indicates the interest status of the email
          example: 0
        thread_id:
          type:
            - 'null'
            - string
          description: >-
            Identifier for the email thread. All the emails in the same thread
            have the same thread ID
          format: uuid
          example: 019e0e3e-7336-7063-ac55-c83f30322f7a
        content_preview:
          type:
            - 'null'
            - string
          description: >-
            A short preview of the email content (usually the first few lines of
            the email)
          example: This is a preview of the email content.
        attachment_json:
          type:
            - 'null'
            - object
          description: >-
            Attachment metadata for the email. This field is null when there are
            no attachments.
          readOnly: true
          properties:
            files:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                  - filename
                properties:
                  filename:
                    type: string
                    description: Attachment file name
                    examples:
                      - attachment.pdf
                  size:
                    type: number
                    description: Attachment file size in bytes
                    examples:
                      - 1927
                  type:
                    type: string
                    description: Attachment MIME type
                    examples:
                      - application/pdf
                  url:
                    type: string
                    format: uri
                    description: Download URL when available
                    examples:
                      - https://cdn.instantly.ai/example-attachment/file.pdf
                  error:
                    type:
                      - 'null'
                      - string
                    description: Error description when the attachment failed to upload
                    examples:
                      - Upload failed
          required:
            - files
          additionalProperties: false
          example:
            files:
              - filename: attachment
                size: 1927
                type: text/css
                url: https://cdn.instantly.ai/example-attachment/
                error: null
        from_address_json:
          type:
            - 'null'
            - array
          description: List of from address details
        to_address_json:
          type:
            - 'null'
            - array
          description: List of to address details
        cc_address_json:
          type:
            - 'null'
            - array
          description: List of CC address details
        ai_agent_id:
          type:
            - 'null'
            - string
          description: ID of the AI agent that sent this email (if applicable)
          format: uuid
          example: 019e0e3e-7336-7063-ac55-c8406ad3db4b
      required:
        - id
        - timestamp_created
        - timestamp_email
        - message_id
        - subject
        - to_address_email_list
        - body
        - organization_id
        - eaccount
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer

````