Post the necessary fields for the API to send a new message.

http
POST https://services.leadconnectorhq.com/conversations/messages

Authorization

NameTypeRequiredExampleDescription
AuthorizationstringYesBearer token generated from the Leadway portal. See Authentication.
VersionstringYes2021-07-28API version.

Body

NameTypeRequiredExampleDescription
typestringYesEmailType of message being sent Possible values: 'SMS', 'RCS', 'Email', 'WhatsApp', 'IG', 'FB', 'Custom', 'Live_Chat', 'TIKTOK'
subTypeobjectYesEmailType of message being sent
contactIdstringYesabc123def456ID of the contact receiving the message
appointmentIdstringNoappt123ID of the associated appointment
attachmentsstring[]NoArray of attachment URLs
emailFromstringNosender@company.comEmail address to send from
emailCcstring[]NoArray of CC email addresses
emailBccstring[]NoArray of BCC email addresses
htmlstringNo<p>Hello World</p>HTML content of the message
messagestringNoHello, how can I help you today?Text content of the message
subjectstringNoImportant UpdateSubject line for email messages
replyMessageIdstringNomsg123ID of message being replied to
templateIdstringNotemplate123ID of message template
threadIdstringNothread123ID of message thread. For email messages, this is the message ID that contains multiple email messages in the thread
scheduledTimestampnumberNo1669287863UTC Timestamp (in seconds) at which the message should be scheduled
conversationProviderIdstringNoprovider123ID of conversation provider
emailTostringNorecipient@company.comEmail address to send to, if different from contact's primary email. This should be a valid email address associated with the contact.
customSubtypeIdstringNo507f1f77bcf86cd799439011Custom subtype ID for email unsubscription preferences. Only applies to email messages.
emailReplyModestringNoreply_allMode for email replies Possible values: 'reply', 'reply_all'
fromNumberstringNo+1499499299Phone number used as the sender number for outbound messages
toNumberstringNo+1439499299Recipient phone number for outbound messages
forwardobjectNoForwarding configuration for emails
statusstringYesdeliveredMessage status Possible values: 'delivered', 'failed', 'pending', 'read'
usesNativeSchedulingAibooleanNoFalseWhether the scheduled email uses native AI for the email scheduling
optimizationPeriodstringNo24hOptimization period in hours (24h, 48h, or 72h) Possible values: '24h', '48h', '72h'

Responses

200 - Created the message
  • conversationId (string, required): Conversation ID. Example: ABC12h2F6uBrIkfXYazb

  • emailMessageId (string): This contains the email message id (only for Email type). Use this ID to send inbound replies to GHL to create a threaded email. Example: rnGyqh2F6uBrIkfhFo9A

  • messageId (string, required): This is the main Message ID Example: t22c6DQcTDf3MjRhwf77

  • messageIds (string[]): When sending via the GMB channel, we will be returning list of messageIds instead of single messageId.

  • msg (string): Additional response message when sending a workflow message Example: Message queued successfully.

  • forwardData (object): Optional metadata for forwarded email

  • status (string, required): Message status Possible values: 'delivered', 'failed', 'pending', 'read' Example: delivered

json
{
  "conversationId": "ABC12h2F6uBrIkfXYazb",
  "emailMessageId": "rnGyqh2F6uBrIkfhFo9A",
  "messageId": "t22c6DQcTDf3MjRhwf77",
  "messageIds": [
    "string"
  ],
  "msg": "Message queued successfully.",
  "forwardData": {
    "forwardWholeThread": false,
    "messageId": "t22c6DQcTDf3MjRhwf77",
    "emailMessageId": "rnGyqh2F6uBrIkfhFo9A",
    "forwardToEmail": "recipient@example.com",
    "recipientContactId": "DEF56h2F6uBrIkfXYacd"
  },
  "status": "delivered"
}
400 - Bad Request
json
{}
401 - Unauthorized
json
{}

Example

curl -X POST 'https://services.leadconnectorhq.com/conversations/messages' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "Email",
  "subType": "Email",
  "contactId": "abc123def456",
  "appointmentId": "appt123",
  "attachments": [
    "https://storage.com/file1.pdf",
    "https://storage.com/file2.jpg"
  ],
  "emailFrom": "sender@company.com",
  "emailCc": [
    "cc1@company.com",
    "cc2@company.com"
  ],
  "emailBcc": [
    "bcc1@company.com",
    "bcc2@company.com"
  ],
  "html": "<p>Hello World</p>",
  "message": "Hello, how can I help you today?",
  "subject": "Important Update",
  "replyMessageId": "msg123",
  "templateId": "template123",
  "threadId": "thread123",
  "scheduledTimestamp": 1669287863,
  "conversationProviderId": "provider123",
  "emailTo": "recipient@company.com",
  "customSubtypeId": "507f1f77bcf86cd799439011",
  "emailReplyMode": "reply_all",
  "fromNumber": "+1499499299",
  "toNumber": "+1439499299",
  "forward": {
    "isForwarded": true,
    "forwardWholeThread": false,
    "messageId": "t22c6DQcTDf3MjRhwf77",
    "emailMessageId": "rnGyqh2F6uBrIkfhFo9A",
    "toEmail": "forward@example.com",
    "recipientContactId": "DEF56h2F6uBrIkfXYacd"
  },
  "status": "delivered",
  "usesNativeSchedulingAi": false,
  "optimizationPeriod": "24h"
}'

Last updated October 26, 2026

Was this page helpful?