---
title: "Send a message from an internal endpoint"
method: POST
path: "/internalendpoints/{internalEndpointId}/conversations"
tags: ["Internal Endpoints"]
---

# Send a message from an internal endpoint

`POST /internalendpoints/{internalEndpointId}/conversations`

This operation sends a message to an external endpoint (phone number or email address) or a contact (secure messaging). Only one of secureEndpoint or smsOrEmailEndpoint should be specified. You will need to also specify the appropriate internal endpoint from the [list of available internal endpoints for an organization](/reference/internalendpoints). The RequestID returned by this API may be used to match against the `RequestID` field of the `conversationItem.created` webhook event to identify when the message is posted.

## Send a secure message
* Get the appropriate Spruce phone number from the [list of internal endpoints for an organization](/reference/internalendpoints) (of channel type `secure`)
* Specify the internal endpoint's `endpoint.Id` in the `internalEndpointId` path parameter
* Get the Id of the appropriate contact to send the secure message to. You can [list all contacts in the organization](/reference/listcontacts) or [search for the appropriate contact](/reference/searchcontacts) to determine the contact Id if you do not have it already.
* Populate the `destination.secureEndpoint` object with the `contactId`, the appropriate `deliveryMethod` and `subject` for the conversation.

The `deliveryMethod` can be one of the following:
* (Default) `any_available_secure_conversation`: The system will first try to deliver messages using conversations from the specified internal endpoint. Then it will try to deliver to any existing secure conversation with the recipient. Then, if no conversation exists, a new secure conversation will be created.
* `only_conversations_matching_internal_endpoint`: The system will deliver messages in conversations from the specified internal endpoint. If such a conversation doesn't yet exist, a new one will be created.
* `new_conversation`: This option will create a new conversation, separate from any existing conversation.
## Send an SMS
* Get the appropriate Spruce phone number from the [list of internal endpoints for an organization](/reference/internalendpoints) (of channel type `phone`)
* Specify the internal endpoint's `endpoint.Id` in the `internalEndpointId` path parameter
* Specify the phone number to send the the message to in the `destination.smsOrEmailEndpoint` body parameter
## Send an email
* Get the appropriate Spruce phone number from the [list of internal endpoints for an organization](/reference/internalendpoints) (of channel type `email`)
* Specify the internal endpoint's `endpoint.Id` in the `internalEndpointId` path parameter
* Specify the email address to send the the message to in the `destination.smsOrEmailEndpoint` body parameter
## Send a fax
* Get the appropriate Spruce fax number from the [list of internal endpoints for an organization](/reference/internalendpoints) (of channel type `fax`)
* Specify the internal endpoint's `endpoint.Id` in the `internalEndpointId` path parameter
* Specify the fax number to send the the message to in the `destination.faxEndpoint` body parameter
* Note: Each outbound fax message sent from an internal endpoint will result in a new fax conversation being created

## Path parameters

- `internalEndpointId` string, required

## Headers

- `s-idempotency-key` string

## Request body

- object
  - `destination` object, required
    - `faxEndpoint` string — The fax number to send the message to.
    - `secureEndpoint` object
      - `contactId` string, required — The Spruce id of the contact to send the message to.
      - `deliveryMethod` 'any_available_secure_conversation' | 'only_conversations_matching_internal_endpoint' | 'new_conversation' — `any_available_secure_conversation`: The system will first try to deliver messages using conversations from the specified internal endpoint. Then it will try to deliver to any existing secure conversation with the recipient. Then, if no conversation exists, a new secure conversation will be created. `only_conversations_matching_internal_endpoint`: The system will deliver messages in conversations from the specified internal endpoint. If such a conversation doesn't yet exist, a new one will be created. `new_conversation`: This option will create a new conversation, separate from any existing conversation.
      - `subject` string — The subject of the message.
    - `smsOrEmailEndpoint` string — The phone number or email address to send the message to.
  - `message` ConversationMessagePost, required
    - `attachments` ConversationMessagePostAttachment[]
      - `attachmentId` string, required — The id of the attachment. In most cases, this will be a media id returned from posting a file to the [media endpoint](/reference/uploadmedia).
      - `title` string, required — The title of the attachment
    - `author` string — The ID of the organization member (teammate, team, or organization) to send the message as. If not provided, defaults to the organization.
    - `body` ConversationMessageBodyElement[], required
      - `type` 'text' | 'page', required
      - `value` string, required — The value of the message body element
    - `internal` boolean — Whether the message is internal or not
    - `stayArchived` boolean — Whether the conversation should stay archived (if it is already archived) after the message is sent
  - `sendAt` string, date-time — The date and time the message is scheduled to be sent

## Response `200`

ok response

- object
  - `requestId` string, required — The id of an asynchronous request

## Other responses

- `400` — bad request
- `422` — duplicate request
- `500` — unexpected error

---

[API](https://skmtc.net/sprucehealth/apis/spruce-health-api.md) · [All operations](https://skmtc.net/sprucehealth/apis/spruce-health-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sprucehealth/spruce-health-api/revisions/988e298cd9fd/schema)