Inbox Reply

Inbox Reply

Manage and reply to lead responses in the email sequencing inbox.

Environment

Base URL: https://api.instantly.ai/api/v2

Inputs

Workflow

Step 1: Fetch unread replies

Fetch unread received emails from the unibox.

List unread: GET /emails with is_unread=true, email_type=received, sort_order=desc, limit=50.

If the user specifies a campaign, add campaign_id filter. If they want focused inbox only, add mode=emode_focused.

Present a summary table:

| # | From | Company | Subject | Preview | Received |

Ask the user which conversations to work on, or process all.

Step 2: Load full threads

For each selected reply, load the full conversation thread.

Get thread: GET /emails?search=thread:{thread_id}&sort_order=asc

This returns the original outbound email(s) and all replies in chronological order, giving full context for drafting a response.

Step 3: Classify reply intent

Read each lead reply and classify into one of these categories:

Interested        → wants to learn more, asks questions, requests a call
Objection         → raises concern but door is not closed (pricing, timing, fit)
Not interested    → clear rejection, asks to stop
Auto-reply        → OOO, bounce, auto-responder
Meeting request   → explicitly asks to book time
Question          → asks a specific question without clear buying signal
Referral          → redirects to someone else at the company

Present classifications to the user for confirmation before drafting.

Step 4: Draft replies

Read the context file for voice rules, product description, proof points, and use case framings. Draft a reply for each conversation based on intent:

Interested       → confirm interest, propose next step (call or resource)
Objection        → address concern directly, offer proof point if relevant
Question         → answer the question, bridge to value
Meeting request  → confirm availability, suggest booking link or times
Referral         → thank them, ask for intro or reach out to referral directly
Not interested   → short, respectful close; do not push
Auto-reply       → skip, no reply needed

Rules for all replies:

• Match the lead's tone and length — short replies get short responses
• Reference specifics from their message to show it is not a template
• Reference the original outbound context when relevant
• Never start with "I" as the first word
• No generic openers ("Thanks for getting back to me", "Great to hear from you")
• One clear call to action per reply, never two
• No attachments unless the user explicitly provides one
• Plain text unless the original thread was HTML-formatted

Present each draft alongside the original thread for the user to review and edit.

Step 5: Confirm and send

Before sending, present a final checklist for each reply:

| # | To | Via Account | Subject | Intent | Action |

The user must confirm before any reply is sent.

Send reply: POST /emails/reply with:

• eaccount: the same email account that sent the original outbound
• reply_to_uuid: the ID of the lead's most recent message
• subject: keep the existing thread subject (Re: ...)
• body: the approved reply in { "text": "...", "html": "..." }

Send one at a time. Report success or failure for each.

Step 6: Post-reply housekeeping

After sending:

1. Mark thread as read: POST /emails/threads/{thread_id}/mark-as-read 2. Update lead interest status if the classification warrants it: POST /leads/update-interest-status with lead_email and appropriate interest_value 3. Report final summary:

| # | Lead | Intent | Reply Sent | Status Updated |

Step 7: Skip and defer handling

For replies the user wants to skip or defer:

• Skip (not interested / auto-reply): mark as read, optionally update interest status
• Defer: leave unread, note for next session

Never send a reply the user has not explicitly approved.

Reference

See references/instantly-inbox-api.md for full Instantly Unibox and Reply API documentation.

Instantly Inbox & Reply API Reference

Base URL: https://api.instantly.ai/api/v2 Auth: Bearer token via INSTANTLY_API_KEY environment variable.

List Emails (Unibox)

GET /emails?limit=50&is_unread=true&email_type=received&sort_order=desc

Rate limit: 20 requests per minute (stricter than other endpoints).

Key query parameters:

Response:

{
  "items": [
    {
      "id": "UUID",
      "timestamp_email": "ISO datetime",
      "subject": "string",
      "from_address_email": "email",
      "to_address_email_list": "string",
      "body": { "text": "string", "html": "string" },
      "campaign_id": "UUID or null",
      "lead": "email or null",
      "lead_id": "UUID or null",
      "eaccount": "string",
      "ue_type": 1 | 2 | 3 | 4,
      "is_unread": 0 | 1,
      "is_auto_reply": 0 | 1,
      "ai_interest_value": "number or null",
      "i_status": "number or null",
      "thread_id": "UUID or null",
      "content_preview": "string or null",
      "attachment_json": "object or null"
    }
  ],
  "next_starting_after": "string"
}

ue_type values: 1 = sent from campaign, 2 = received, 3 = sent manually, 4 = scheduled.

Get Single Email

GET /emails/{id}

Returns full email object including body.text and body.html.

Get Thread

To load a full conversation thread, use the list endpoint with thread filter:

GET /emails?search=thread:{thread_id}&sort_order=asc

Reply to an Email

POST /emails/reply

Body:

{
  "eaccount": "sender@domain.com",
  "reply_to_uuid": "email-uuid-to-reply-to",
  "subject": "Re: Original Subject",
  "body": {
    "html": "<p>Reply content here</p>",
    "text": "Reply content here"
  },
  "cc_address_email_list": "optional@cc.com",
  "bcc_address_email_list": "optional@bcc.com"
}

Required fields: eaccount, reply_to_uuid, subject, body.

Response: full email object of the sent reply.

Mark Thread as Read

POST /emails/threads/{thread_id}/mark-as-read

Response: { "success": true }

Patch Email

PATCH /emails/{id}

Patchable fields (at least one required):

Count Unread Emails

GET /emails/unread/count

Response: { "count": 100 }

Update Lead Interest Status

POST /leads/update-interest-status

Body:

{
  "lead_email": "lead@company.com",
  "interest_value": 1,
  "campaign_id": "optional-campaign-uuid"
}

Set interest_value to null to reset to default "Lead" status.

Response (202): { "message": "Lead interest status update background job submitted" }

Rate Limits

• List emails: 20 requests per minute
• All other endpoints: 10 requests per second