> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/reference-guides/channel-manager-email-templates.md).

# Send Email With a Channel Manager Template

Create a reusable Channel Manager email template, inspect its required variables, send a controlled message, and manage updates and cleanup within its use case.

An email template stores a reusable subject and HTML body for one email use case. Your application supplies the template's variables when sending. The template does not choose recipients, schedule delivery, or establish consent.

Complete [Channel Manager setup](https://docs.concurrence.com/developer-guide/reference-guides/integrate-channel-manager.md) with a verified email sender and a controlled test mailbox. Use Bash, cURL, and `jq`, with the guide's API host, use-case ID, and token variables. Obtain an administrative token in `CHANNEL_ADMIN_ACCESS_TOKEN` with `email:template:read email:template:write` on the email setup. Keep `CHANNEL_ACCESS_TOKEN` as the runtime token with `email:send email:read`.

The [template reference](https://docs.concurrence.com/developer-guide/platform-api/conversations/channel-manager.md#manage-email-templates) contains the canonical operations. Template creation uses `ses_use_case_id`, and email sending uses `use_case_id`. Both identify the same provisioned email use case.

## Create a Template

This example requires an **unsubscribable** email use case. Its body includes both reserved unsubscribe variables. For a non-unsubscribable use case, use approved content without those links. Subjects cannot contain unsubscribe variables. Keep template names unique within the use case. Set `CHANNEL_TEMPLATE_NAME` to a new test name such as `Member follow-up test 01`.

```bash
set -euo pipefail
TEMPLATE_RESPONSE=$(jq -n \
  --arg use_case "$CHANNEL_USE_CASE_ID" \
  --arg name "$CHANNEL_TEMPLATE_NAME" \
  '{ses_use_case_id: $use_case, name: $name, description: null,
    subject_template: "A message from {{ team_name }}",
    body_template: (
      "<p>Hello {{ member_name }}, this is a test from {{ team_name }}.</p>" +
      "<p><a href=\"{{ unsubscribe_link }}\">Unsubscribe from this program</a> | " +
      "<a href=\"{{ unsubscribe_from_all_link }}\">Unsubscribe from all email</a></p>"
    )}' | \
  curl --fail-with-body --silent --show-error \
    --request POST "$CHANNEL_API_BASE/v1/email/template" \
    --header "Authorization: Bearer $CHANNEL_ADMIN_ACCESS_TOKEN" \
    --header 'Content-Type: application/json' --data-binary @-)
CHANNEL_TEMPLATE_ID=$(printf '%s' "$TEMPLATE_RESPONSE" | jq -er '.id')
printf '%s' "$TEMPLATE_RESPONSE" | \
  jq '{id, required_subject_variables, required_body_variables}'
unset TEMPLATE_RESPONSE
```

Save the template ID. If creation times out, list this use case's templates and inspect the matching name before creating another:

```bash
curl --fail-with-body --silent --show-error --get \
  "$CHANNEL_API_BASE/v1/email/template" \
  --header "Authorization: Bearer $CHANNEL_ADMIN_ACCESS_TOKEN" \
  --data-urlencode "ses_use_case_id=$CHANNEL_USE_CASE_ID"

curl --fail-with-body --silent --show-error \
  "$CHANNEL_API_BASE/v1/email/template/$CHANNEL_TEMPLATE_ID" \
  --header "Authorization: Bearer $CHANNEL_ADMIN_ACCESS_TOKEN"
```

The list contains summaries. The individual read contains the subject, body, and required variable sets. Supply the union of those sets at send time, **excluding** `unsubscribe_link` and `unsubscribe_from_all_link`. Channel Manager generates those two values, and supplying either in `template_parameters` is rejected. Template parameter values are strings.

## Send and Verify

Set `CHANNEL_TEST_EMAIL` to your controlled mailbox. This request sends one email using synthetic values. Use the template's own use case:

```bash
SEND_RESPONSE=$(curl --fail-with-body --silent --show-error \
  --request POST "$CHANNEL_API_BASE/v1/email/" \
  --header "Authorization: Bearer $CHANNEL_ACCESS_TOKEN" \
  --form-string "use_case_id=$CHANNEL_USE_CASE_ID" \
  --form-string "to_address=$CHANNEL_TEST_EMAIL" \
  --form-string 'mode=template' \
  --form-string "template_id=$CHANNEL_TEMPLATE_ID" \
  --form-string 'template_parameters={"member_name":"Test member","team_name":"Example team"}')
CHANNEL_EMAIL_ID=$(printf '%s' "$SEND_RESPONSE" | jq -er '.id')
unset SEND_RESPONSE

curl --fail-with-body --silent --show-error \
  "$CHANNEL_API_BASE/v1/email/$CHANNEL_EMAIL_ID" \
  --header "Authorization: Bearer $CHANNEL_ACCESS_TOKEN"
```

Verify the rendered subject, body, sender, and unsubscribe links in the mailbox. Read delivery events as shown in the [email walkthrough](https://docs.concurrence.com/pages/TWFPrOxAvAp4FKKfh07v#id-4.-send-one-controlled-message-and-read-the-result). A template from another use case is refused, and missing required variables are refused. If the send response is lost, [reconcile the attempt](https://docs.concurrence.com/developer-guide/reference-guides/reconcile-channel-manager.md) before resending.

For a reply, add `reply_to_inbound_email_id` with the inbound Channel Manager email ID from this setup and use case. The template selects content, and the reply ID establishes threading.

## Update and Clean Up

Template updates modify the existing template. Omitted fields retain their values, and an explicit `description: null` clears the description. Read the template after an update because its required variables can change. Coordinate updates with every application that uses that ID. Create a separate template when you need to test new content before switching callers to it.

After the controlled test, stop using its template ID and delete that temporary template:

```bash
curl --fail-with-body --silent --show-error --request DELETE \
  "$CHANNEL_API_BASE/v1/email/template/$CHANNEL_TEMPLATE_ID" \
  --header "Authorization: Bearer $CHANNEL_ADMIN_ACCESS_TOKEN"
unset CHANNEL_ADMIN_ACCESS_TOKEN CHANNEL_ACCESS_TOKEN
```

Deletion removes the reusable template. It does not recall an email. Retain the test message and consent records according to your policy. Coordinate any unsubscribe test and restoration with the channel operator before further sends.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/reference-guides/channel-manager-email-templates.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
