INinstantly
Email

Patch email

Changed on

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

patch/api/v2/emails/{id}

Request

  • Base URL
    https://api.instantly.ai
  • URL
    https://api.instantly.ai/api/v2/emails/{id}
  • Auth
    HTTP bearer

Path parameters

idstring uuid required
Example:01a19e6f-8865-7d7c-8dbd-134e1d32b091

The ID of the item to update

Request body

is_unreadnumber nullable

Indicates if the email is unread

reminder_tsstring date-time nullable

Timestamp for the reminder.

Example request

{
  "is_unread": 1,
  "reminder_ts": "2026-11-02T22:44:13.292Z"
}

Response

The updated Email

idstring uuid required

A Unique identifier

timestamp_createdstring date-time required

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.

timestamp_emailstring date-time required

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.

message_idstring required

Unique email ID from the email server

subjectstring required

Subject line of the email message

from_address_emailstring email nullable

The sender email address, populated based on the eaccount

to_address_email_liststring required

Comma-separated list of recipient email addresses

cc_address_email_liststring nullable

Comma-separated list of CC email addresses

bcc_address_email_liststring nullable

Comma-separated list of BCC email addresses

reply_tostring nullable

Reply-to email address

organization_idstring uuid required

The workspace ID

campaign_idstring uuid nullable

The id of the campaign that the email is associated with (it can be null for manually sent emails)

subsequence_idstring uuid nullable

The id of the campaign subsequence that the email is associated with (it can be null for manually sent emails)

list_idstring uuid nullable

The id of the list (if the lead is part of a list)

leadstring nullable

The email address of the lead that the email is associated with

lead_idstring uuid nullable

The lead id (if any)

eaccountstring required

The email account that was used to send the email. This needs to be validated to make sure it exists in the user workspace

ue_type1 | 2 | 3 | 4 nullable

Email type based on the life cycle of the email

stepstring nullable

The campaign step that the email is associated with

is_unreadnumber nullable

Indicates if the email is unread

is_auto_replynumber nullable

Indicates if the email is an auto-reply. 0 (zero) - is false, and 1 is true

reminder_tsstring date-time nullable

Timestamp for the reminder.

ai_interest_valuenumber nullable

AI interest value

ai_assistednumber nullable

Indicates if AI assistance was used

is_focusednumber nullable

Indicates if the email is focused (is in the primary tab in the Unibox)

i_statusnumber nullable

Indicates the interest status of the email

thread_idstring uuid nullable

Identifier for the email thread. All the emails in the same thread have the same thread ID

content_previewstring nullable

A short preview of the email content (usually the first few lines of the email)

body_fallback_reason'too_large' | 'unavailable' nullable

Set only when body is not the full email body. too_large: the body was too large to include in a list response. unavailable: the body could not be read for this response. In both cases body holds at most a plain-text excerpt (text, no html) and may be empty. Get the full body from GET /api/v2/emails/{id}.

ai_agent_idstring uuid nullable

ID of the AI agent that sent this email (if applicable)

Example response

{
  "id": "01a19e6f-3f6c-788a-bd91-c9a3fa33979f",
  "timestamp_created": "2026-11-02T22:44:13.292Z",
  "timestamp_email": "2026-11-02T22:44:13.292Z",
  "message_id": "<example123@mail.gmail.com>",
  "subject": "Re: Your inquiry",
  "from_address_email": "sender@example.com",
  "to_address_email_list": "recipient@example.com",
  "cc_address_email_list": "cc@example.com",
  "bcc_address_email_list": "bcc@example.com",
  "reply_to": "replyto@example.com",
  "body": {
    "text": "This is a test email",
    "html": "This is a test email.<br/><br/>Second line."
  },
  "organization_id": "01a19e6f-3f6c-788a-bd91-c9a4b9e2f6a8",
  "campaign_id": "01a19e6f-3f6c-788a-bd91-c9a5d09ccd4f",
  "subsequence_id": "01a19e6f-3f6c-788a-bd91-c9a6fff00dea",
  "list_id": "01a19e6f-3f6c-788a-bd91-c9a71ca31e74",
  "lead": "jondoe@example.com",
  "lead_id": "01a19e6f-3f6c-788a-bd91-c9a8bf68f3bd",
  "eaccount": "eaccount-123",
  "ue_type": 3,
  "step": "step-123",
  "is_unread": 1,
  "reminder_ts": "2026-11-02T22:44:13.292Z",
  "ai_interest_value": 0.75,
  "ai_assisted": 1,
  "is_focused": 1,
  "thread_id": "01a19e6f-3f6c-788a-bd91-c9a9995aed4c",
  "content_preview": "This is a preview of the email content.",
  "body_fallback_reason": "too_large",
  "attachment_json": {
    "files": [
      {
        "filename": "attachment",
        "size": 1927,
        "type": "text/css",
        "url": "https://cdn.instantly.ai/example-attachment/",
        "error": null
      }
    ]
  },
  "ai_agent_id": "01a19e6f-3f6c-788a-bd91-c9aa80bc937e"
}

Changes