Message Drafts

Use the message drafts endpoint to create outbound first-contact messages that can be reviewed, saved, and queued for delivery.

Create a message draft

POST /api/v2/organizations/{organization_id}/message-drafts

This endpoint creates a message draft in the specified organization.

This route is intended for new outbound outreach. For follow-ups on an existing conversation, see the Response Drafts route.

Set modality to the draft delivery channel. Supported values are email and text.

Message drafts use body_html for the outbound body. Provide at least one of subject or body_html.

The API verifies that the organization has credentials configured for the selected modality before creating the draft.

autosend_draft and add_notification are mutually exclusive. If autosend_draft=true, set add_notification=false.

When autosend_draft=true, the draft is queued for delivery immediately and the response includes the queue timestamp in scheduled_send_at. Otherwise, the draft is saved for later review and sending. When add_notification=true (and autosend_draft=false), users in the organization can be notified that a new draft is ready for review.

Create message draft request

curl https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/message-drafts \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "modality": "email",
    "subject": "Following up on your quote",
    "body_html": "<p>Hi Diana, checking in on the quote we sent yesterday.</p>",
    "to_user_name": "Diana Prince",
    "to_email": "[email protected]",
    "to_phone_number": "513-867-5309",
    "cc_emails": ["[email protected]"],
    "bcc_emails": [],
    "autosend_draft": false,
    "add_notification": true,
    "folder": "Sales Follow-up"
  }'

Example response (saved message draft)

{
  "draft_id": "HR_id_example_message_draft_id",
  "scheduled_to_send": false,
  "scheduled_send_at": null,
  "folder": "sales-follow-up"
}

Example response (queued to send)

{
  "draft_id": "HR_id_example_message_draft_id",
  "scheduled_to_send": true,
  "scheduled_send_at": "2026-05-02T21:17:42.130649Z",
  "folder": "sales-follow-up"
}

List message drafts

GET /api/v2/organizations/{organization_id}/message-drafts

Returns a paginated collection of message drafts scoped to the organization.

Supports optional limit, cursor, start_date, and end_date query parameters.

List message drafts request

curl -G https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/message-drafts \
  -H "X-API-KEY: your-api-key" \
  --data-urlencode "limit=25"

Example response

{
  "data": [
    {
      "draft_id": "HR_id_example_message_draft_id",
      "subject": "Following up on your quote",
      "body_html": "<p>Hi Diana, checking in on the quote we sent yesterday.</p>",
      "modality": "email",
      "agent_id": "HR_id_example_agent_id",
      "recipient_name": "Diana Prince",
      "recipient_email": "[email protected]",
      "recipient_phone_number": "513-867-5309",
      "cc_emails": [],
      "bcc_emails": [],
      "scheduled_send_at": null,
      "folder": "sales-follow-up",
      "created_at": "2026-05-21T14:30:00Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": null,
    "has_more": false
  }
}

Get a message draft

GET /api/v2/organizations/{organization_id}/message-drafts/{draft_id}

Returns one message draft by ID.

If the draft has already been promoted into a conversation, this endpoint returns 404 with guidance to use the conversation route.

If the ID belongs to a response draft instead of a message draft, this endpoint also returns 404 with guidance to use the response drafts route.

Get message draft request

curl https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/message-drafts/HR_id_example_message_draft_id \
  -H "X-API-KEY: your-api-key"

Example response

{
  "draft_id": "HR_id_example_message_draft_id",
  "subject": "Following up on your quote",
  "body_html": "<p>Hi Diana, checking in on the quote we sent yesterday.</p>",
  "modality": "email",
  "agent_id": "HR_id_example_agent_id",
  "recipient_name": "Diana Prince",
  "recipient_email": "[email protected]",
  "recipient_phone_number": "513-867-5309",
  "cc_emails": [],
  "bcc_emails": [],
  "scheduled_send_at": null,
  "folder": "sales-follow-up",
  "created_at": "2026-05-21T14:30:00Z"
}

Delete a message draft

DELETE /api/v2/organizations/{organization_id}/message-drafts/{draft_id}

Deletes one message draft by ID.

On success, the API returns 204 No Content.

If the draft has already been promoted into a conversation, this endpoint returns 404 with guidance to use the conversation route.

If the draft is currently sending, this endpoint returns 400.

Delete message draft request

curl -X DELETE https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/message-drafts/HR_id_example_message_draft_id \
  -H "X-API-KEY: your-api-key"

Draft lifecycle lookups

Name
Promotion (message draft -> conversation)
Description
After a draft is sent and promoted into a conversation, the draft is no longer returned by message-draft detail lookups. You receive 404 plus a route hint to the conversation endpoint.
Name
Cross-route ID lookup
Description
If you call message-draft detail with an ID that actually belongs to a response draft, you receive 404 plus a route hint to the response-drafts detail endpoint.
Name
Why this exists
Description
It prevents stale draft IDs from silently returning wrong data and gives a deterministic route to continue the workflow.

Request body fields

Name
modality
Description
Required draft delivery channel. Use email for an email draft or text for a text message draft. The organization must have credentials configured for the selected modality.
Name
subject
Description
Optional message draft subject line.
Name
body_html
Description
Optional HTML message body. You must provide subject or body_html (or both).
Name
to_user_name
Description
Optional recipient display name.
Name
to_email
Description
Optional recipient email address. Provide this for email drafts.
Name
to_phone_number
Description
Optional recipient phone number. Provide this for text drafts.
Name
cc_emails
Description
Optional list of CC email addresses.
Name
bcc_emails
Description
Optional list of BCC email addresses.
Name
autosend_draft
Description
When true, the draft is queued for asynchronous delivery immediately.
Name
add_notification
Description
Applies only when autosend_draft=false. If autosend_draft=true, this must be false.
Name
folder
Description
Optional folder name for organizing drafts. The response returns the normalized folder value (for example, Sales Follow-up becomes sales-follow-up). If omitted, drafts use drafts.

Response fields

Name
draft_id
Description
Encoded draft identifier returned by the draft-create call.
Name
scheduled_to_send
Description
true when the draft has been queued for delivery.
Name
scheduled_send_at
Description
Timestamp when the draft was queued for delivery. null for drafts saved for later review.
Name
sent_at
Description
Not returned by this endpoint. Delivery happens asynchronously after a draft is queued.
Name
folder
Description
Normalized folder value assigned to the draft.

Delivery behavior

This endpoint creates message drafts and queues sends. Message delivery may not happen immediately due to asynchronous processing.

Name
Saved message draft flow
Description
Use autosend_draft=false (default) to save for review. You can keep add_notification=true so users are notified a new message draft exists.
Name
Queued send flow
Description
Use autosend_draft=true with add_notification=false to queue delivery immediately.
Name
Scoping
Description
Requests are scoped to the organization_id in the path.
Name
Credential validation
Description
Requests fail before draft creation when the organization does not have credentials configured for the requested modality.