---
title: "Draft follow-ups"
method: POST
path: "/api/agent-plans/draft-followups"
tags: ["agent_plans"]
---

# Draft follow-ups

`POST /api/agent-plans/draft-followups`

## Request

- Base URL: `https://beta.getsales.io/unibox/v1`
- URL: `https://beta.getsales.io/unibox/v1/api/agent-plans/draft-followups`
- Auth: HTTP bearer and API key in header `Team-SID`
- TypeScript: <https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox/docs/api/agent-plans/draft-followups/post.ts> (a function with typed inputs; its response is checked against the schema)

Write the follow-ups that continue the team's last message on a thread (the composer's Make follow-ups): how many, how many days apart, in the sender's words or the AI SDR's; each comes with its time (ten in the morning of the workspace's day, the weekend skipped). Nothing is saved: read them back, edit, then schedule_followups. 503 composer_unavailable when the runner did not answer. The agent's own token is 403 (human_verb_only).

Contract:
- MCP tool `draft_followups`, registry package `mcp.unibox/agent_plans`, mount `unibox.agent`.
- Operation `action`, response envelope `action`.
- Flags: read only.

## Request body

- DraftFollowupsRequest: Request body of `draft_followups`.
  - `conversation_sid` string, required: The thread the follow-ups continue (ub_cv_…): its last message of ours is what they follow; when the lead wrote last, they count from now.
  - `every_days` integer: Days between the follow-ups, 1..30; default the agent settings' person_followups_every_days (3).
  - `voice` 'sender' | 'agent': sender: written as the sender profile (the person) would write them, continuing their own message; agent: in the AI SDR's own voice. Default: the last message's author.
  - `count` integer: How many follow-ups to write, 1..3; default the agent settings' person_followups_count (2).
  - `guidance` string, nullable: What should change, in the person's words, when they read a first draft and ask again (shorter, another angle, a name to mention). Max 1000 chars; omit on the first ask.

## Response `200`

`action` success envelope.

- DraftFollowupsResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required: kebab-case verb; matches the route segment.
  - `item` unknown, required
  - `result` object, required
    - `anchor` object, required: The message the follow-ups continue.
      - `message_sid` string, nullable, required: The message the follow-ups continue (ub_ms_…); null on a thread with no message.
      - `at` string, required: When it was sent, ISO 8601; now when the thread holds nothing of ours last.
      - `author` string, nullable, required: Who wrote the last word: user (a person on the team), agent (the AI SDR) or lead; null on a thread with no message.
      - `author_name` string, nullable, required: The sender profile or the agent that wrote it, as the thread names them; null for the lead.
    - `voice` string, required: Whose words the drafts are in: sender or agent.
    - `count` integer, required: How many were written.
    - `every_days` integer, required: The days between them.
    - `then` string, required: What the agent settings say ends them when none is answered: task or agent_continues.
    - `followups` object[], required: The drafts in order, each with its time.
      - `at` string, required: When this follow-up would go, ISO 8601: so many days after the message it continues, at ten in the morning of the workspace's day, never on a weekend.
      - `weekend_skipped` boolean, required: True when the day fell on a weekend and moved to the Monday.
      - `text` string, required: The message as the composer wrote it, in the voice asked for; edit it before scheduling.
    - `cost_usd` number, nullable, required: The composer call's list-price cost; null when unknown.
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-unibox/revisions/8f1bc317897f?raw)