Message Drafts

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

Create a message draft

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

This endpoint creates a message draft in the specified organization.

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

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 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/gAAAAABexampleOrganizationIdReturnedByApi7mN4qP2xLs9dV5kTr8cY1hJ6uW3/messages-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": "gAAAAABexampleDraftIdReturnedByApi6pN8xLm3sV7kRt2cY5hJ9uW1dF4",
  "queued_to_send": false,
  "send_at": null,
  "folder": "sales-follow-up"
}

Example response (queued to send)

{
  "draft_id": "gAAAAABexampleDraftIdReturnedByApi6pN8xLm3sV7kRt2cY5hJ9uW1dF4",
  "queued_to_send": true,
  "send_at": "2026-05-02T21:17:42.130649Z",
  "folder": "sales-follow-up"
}

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 identifier for the created message draft.
Name
queued_to_send
Description
true when the draft has been queued for delivery.
Name
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 is asynchronous after a message draft is queued.

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 and the permissions associated with your API key.
Name
Credential validation
Description
Requests fail before draft creation when the organization does not have credentials configured for the requested modality.