Skip to main content

How to send a text or email to customer

This endpoint allows you to send both text messages and emails to customers. The same API endpoint is used for both communication types - you simply change the protocol field and provide the appropriate contact information.

To use this endpoint, you first need your credentials. If you don't already have one, please head over to the Authentication and Authorization page to see how you can request for credentials from us.

tip
  • For text messages: Set protocol to TEXT and provide a phone number in communicationValueOfCustomer
  • For emails: Set protocol to EMAIL and provide an email address in communicationValueOfCustomer

Need to find or create a customer first? See how to search and create a customer

Request

HTTP request

POST  https://api.mykaarma.com/communications/department/{departmentUUID}/user/{userUuid}/customer/{customerUuid}/message

Parameters

Required path parameters:

Parameter NameValueDescription
departmentUUIDstringUnique identifier of dealer department
userUuidstringUnique identifier of user ( To prevent delegation of the customer conversation thread from any existing Dealer Associate, use the userUuid of the Default DealerAssociate). If you don't use the Default DealerAssociate userUuid, then the thread will be delegated to the DealerAssociate for which the userUuid has been provided.
customerUuidstringUnique identifier of customer

Authorization

This request requires the following authorization scopes:

ScopeLevelDescription
message.createDealerDepartmentAuthorizes client to send text to customers for the provided user's dealer department

Request Body

The request body contains two main objects with nested properties:

messageAttributes (Required)

All properties within this object are required.

Property NameTypeDescription
bodystringMessage body of the text/email to be sent out
isManualbooleanWhether the message is being sent out manually by a user's action (true) or automatically by a system (false)
protocolstringCommunication protocol: TEXT for SMS or EMAIL for email messages
typestringMessage direction. Set to OUTGOING for customer communications and INCOMING for dealership communications

messageSendingAttributes (Optional)

All properties within this object are optional.

Property NameTypeDescription
communicationValueOfCustomerstringFor TEXT: Phone number in E.164 format (e.g., +11234567890) or 10-digit US format (e.g., 1234567890). Must be a valid phone number registered for the customer in myKaarma.
For EMAIL: Valid email address of the customer.
If not provided, the system will use the customer's preferred contact method from myKaarma records.
sendSynchronouslybooleanDefault: false
When to use true: Set to true when you need immediate confirmation of message delivery and must know right away whether the message was successfully delivered or failed. The API will wait for the third-party service (Twilio/email provider) to respond before returning the result.
When to use false: Set to false (recommended for most cases) when immediate delivery confirmation is not required, such as automated messages, bulk communications, or scheduled notifications. The message is queued with automatic retries for better performance, and status updates are sent to your callbackURL if provided.
callbackURLstringYour webhook URL to receive delivery status updates when using asynchronous sending (sendSynchronously: false). Required if you need delivery confirmation for async messages.
callbackMetaDataobjectCustom key-value pairs that will be included in the callback payload. Useful for tracking or correlating messages in your system.
addTCPAFooterbooleanDefault: true
Appends opt-out text (e.g., "Text STOP to opt-out") as configured for the dealership. Applies only to TEXT messages.
addSignaturebooleanDefault: false
Appends the sending user's name (e.g., "-- John Doe") to the message.
addFooterbooleanDefault: false
Appends the dealership footer configured in myKaarma records.
sendVCardbooleanDefault: false
Sends a vCard (contact card) with the department's phone number. Applies only to TEXT messages.

Examples

Example 1: Sending a Text Message (SMS)

This example demonstrates sending an SMS to a customer with common options enabled.

curl --location --request POST 'https://api.mykaarma.com/communications/department/{{departmentUUID}}/user/{{userUuid}}/customer/{{customerUuid}}/message' \
--header 'accept: application/json' \
-u "{{username}}:{{password}}" \
--header 'Content-Type: application/json' \
--data-raw '{
"messageAttributes": {
"body": "Hi John, your vehicle service appointment is confirmed for tomorrow at 10 AM. See you then!",
"isManual": true,
"protocol": "TEXT",
"type": "OUTGOING"
},
"messageSendingAttributes": {
"communicationValueOfCustomer": "1234567890",
"sendSynchronously": false,
"callbackURL": "https://your-domain.com/webhook/message-status",
"callbackMetaData": {
"appointmentId": "12345",
"source": "appointment-reminder"
},
"addTCPAFooter": true,
"addSignature": true,
"addFooter": false,
"sendVCard": false
}
}'

Expected Result: Customer receives SMS:

Hi John, your vehicle service appointment is confirmed for tomorrow at 10 AM. See you then!
-- Sarah Johnson
Text STOP to opt-out

Example 2: Sending an Email

This example demonstrates sending an email to a customer.

curl --location --request POST 'https://api.mykaarma.com/communications/department/{{departmentUUID}}/user/{{userUuid}}/customer/{{customerUuid}}/message' \
--header 'accept: application/json' \
-u "{{username}}:{{password}}" \
--header 'Content-Type: application/json' \
--data-raw '{
"messageAttributes": {
"body": "Dear John,\n\nThank you for choosing our service center. Your vehicle service has been completed.\n\nService Details:\n- Oil Change\n- Tire Rotation\n- Multi-point Inspection\n\nTotal: $89.99\n\nPlease feel free to contact us if you have any questions.\n\nBest regards,\nService Team",
"isManual": false,
"protocol": "EMAIL",
"type": "OUTGOING"
},
"messageSendingAttributes": {
"communicationValueOfCustomer": "customer@example.com",
"sendSynchronously": false,
"callbackURL": "https://your-domain.com/webhook/email-status",
"callbackMetaData": {
"serviceOrderId": "SO-67890",
"communicationType": "service-completion"
},
"addTCPAFooter": false,
"addSignature": true,
"addFooter": true,
"sendVCard": false
}
}'

Example 3: Synchronous Sending (with immediate delivery confirmation)

Use this when you need to know immediately whether the message was successfully delivered or failed, and must display or act on that delivery status right away.

curl --location --request POST 'https://api.mykaarma.com/communications/department/{{departmentUUID}}/user/{{userUuid}}/customer/{{customerUuid}}/message' \
--header 'accept: application/json' \
-u "{{username}}:{{password}}" \
--header 'Content-Type: application/json' \
--data-raw '{
"messageAttributes": {
"body": "Your verification code is: 123456. This code will expire in 5 minutes.",
"isManual": false,
"protocol": "TEXT",
"type": "OUTGOING"
},
"messageSendingAttributes": {
"communicationValueOfCustomer": "+11234567890",
"sendSynchronously": true,
"addTCPAFooter": false,
"addSignature": false,
"addFooter": false,
"sendVCard": false
}
}'
Important Notes
  • Phone Number Format: Accepts E.164 format (+11234567890) or 10-digit US format (1234567890)
  • Email Validation: Email addresses must be valid and registered for the customer in myKaarma
  • Asynchronous vs Synchronous Sending:
    • Use sendSynchronously: false (default, recommended) when immediate delivery confirmation is not needed - provides better performance with automatic retries and background processing. Ideal for automated messages, bulk communications, and scheduled notifications
    • Use sendSynchronously: true only when you must know immediately if the message was delivered or failed, and need to display or act on that status right away
  • TCPA Compliance: addTCPAFooter defaults to true for TEXT messages to ensure compliance with telemarketing regulations

Response

{
"customerUUID": "string",
"errors": [
{
"errorCode": "string",
"errorDescription": "string",
"errorUID": "string"
}
],
"messageUUID": "string",
"metaData": {
"additionalProp1": "string"
},
"requestUUID": "string",
"status": "SUCCESS",
"warnings": [
{
"warningCode": "string",
"warningDescription": "string"
}
]
}