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 Name	Value	Description
`departmentUUID`	`string`	Unique identifier of dealer department
`userUuid`	`string`	Unique 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.
`customerUuid`	`string`	Unique identifier of customer

Authorization

This request requires the following authorization scopes:

Scope	Level	Description
`message.create`	`DealerDepartment`	Authorizes 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 Name	Type	Description
`body`	`string`	Message body of the text/email to be sent out
`isManual`	`boolean`	Whether the message is being sent out manually by a user's action (`true`) or automatically by a system (`false`)
`protocol`	`string`	Communication protocol: `TEXT` for SMS or `EMAIL` for email messages
`type`	`string`	Message direction. Set to `OUTGOING` for customer communications and `INCOMING` for dealership communications

`messageSendingAttributes` (Optional)

All properties within this object are optional.

Property Name	Type	Description
`communicationValueOfCustomer`	`string`	For 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.
`sendSynchronously`	`boolean`	Default: `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.
`callbackURL`	`string`	Your webhook URL to receive delivery status updates when using asynchronous sending (`sendSynchronously: false`). Required if you need delivery confirmation for async messages.
`callbackMetaData`	`object`	Custom key-value pairs that will be included in the callback payload. Useful for tracking or correlating messages in your system.
`addTCPAFooter`	`boolean`	Default: `true` Appends opt-out text (e.g., "Text STOP to opt-out") as configured for the dealership. Applies only to TEXT messages.
`addSignature`	`boolean`	Default: `false` Appends the sending user's name (e.g., "-- John Doe") to the message.
`addFooter`	`boolean`	Default: `false` Appends the dealership footer configured in myKaarma records.
`sendVCard`	`boolean`	Default: `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"
        }
    ]
}

Request​

HTTP request​

Parameters​

Authorization​

Request Body​

messageAttributes (Required)​

messageSendingAttributes (Optional)​

Examples​

Example 1: Sending a Text Message (SMS)​

Example 2: Sending an Email​

Example 3: Synchronous Sending (with immediate delivery confirmation)​

Response​