> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Send a HIPAA-safe appointment reminder

> Text patients 24 hours before an appointment, email them when the text isn't delivered, stop on reschedule, and honor opt-outs, with no PHI in the message.

Text a patient 24 hours before their appointment, email them if the text isn't delivered, and stop the reminder when the appointment moves. Each message says when to come in and links to your app for the rest, so clinical details stay in your system.

**Keep PHI out of the message.** The reminder carries the time and a link, never the reason for the visit or a specialty that reveals one. For BAAs and Courier's HIPAA program, see [HIPAA and BAAs](https://www.courier.com/docs/security/hipaa.md).

## Prerequisites

* [A Courier API key](https://app.courier.com/settings/api-keys)
* [Twilio connected](https://www.courier.com/docs/integrations/sms/twilio.md) with [delivery status polling](https://www.courier.com/docs/send/statuses.md#delivery-tracking-is-per-provider) turned on, so Courier knows whether each text arrived
* [A connected email provider](https://www.courier.com/docs/integrations/email/overview.md)
* [Your patients stored in Courier](https://www.courier.com/docs/guides/import-your-users.md) with a phone number, an email address, and a timezone

## Build the Journey

**1. Create the Journey and its trigger**

Open [Journeys](https://app.courier.com/orchestration/journeys), select **New Journey**, name it `appointment-reminder`, and choose the **API Invoke** trigger.

Add three fields to the trigger schema:

* `appointment_id`: your ID for the appointment
* `appointment_at`: when the appointment starts, as an ISO 8601 datetime
* `remind_at`: when to send the reminder, as an ISO 8601 datetime. Your app computes it, 24 hours before `appointment_at`

**2. Add an appointment reminders topic**

In the [preferences editor](https://app.courier.com/~/test/platform/preferences), add a topic named **Appointment reminders** with the default **On**. Leave it off **Required**, so patients can opt out.

You'll map both reminder templates to this topic. Mapping a template to a topic makes Courier enforce the patient's preference on every send. See [Build a preference center](https://www.courier.com/docs/guides/build-a-preference-center.md).

**3. Wait until the reminder time**

Add a **delay** node, set the interval type to **Until**, and turn on **Dynamic Interval**. Select `data.remind_at` as the field. Each patient's run waits until their own reminder time.

**4. Send the SMS reminder**

Add a **send** node on the **SMS** channel and select **+ Create** to write the template. Use the clinic name, the time, and a link, and nothing about why the patient is coming in:

```text theme={null}
Northside Health: you have an appointment tomorrow at {{datetime-format appointment_at "h:mm a" (default profile.timezone "America/New_York")}}. Confirm or reschedule: https://app.example.com/appointments/{{appointment_id}} Reply STOP to opt out.
```

`datetime-format` shows the time in the patient's timezone from their profile, and in New York time when it isn't set. See [Variables](https://www.courier.com/docs/design/templates/variables.md). In the template's settings, set the subscription topic to **Appointment reminders**.

**5. Give the text time to arrive**

Add a **delay** of 30 minutes. Courier polls Twilio for each text's status, so a check made right after the send would find most texts not yet delivered.

**6. Email the patient if the text wasn't delivered**

Add a send node on the **Email** channel with the same reminder, and map its template to the **Appointment reminders** topic too.

Give it one condition: `send_status.<SMS node ID>` **was not** `DELIVERED`. The node ID is the SMS node's `id`, shown in the editor and returned when you create the Journey over the API. Patients whose text arrived skip the email. Patients whose text failed, or who have no phone number, get it. A text still waiting on carrier status after 30 minutes also triggers the email, so lengthen the delay if your carriers report slowly.

**7. Set a cancelation token and publish**

In the Journey's settings, set the **cancelation token** to `appt-{{data.appointment_id}}`. Each appointment's run carries its own token, so a reschedule stops only that reminder. Always pass `appointment_id`, because a token that references missing data isn't set.

Publish both templates, then select **Publish** on the Journey and copy its ID.

## Trigger it from your app

**1. Start the reminder when an appointment is booked**

Call [`POST /journeys/{templateId}/invoke`](https://www.courier.com/docs/api-reference/journeys/invoke-a-journey) from the code that books the appointment. Replace `appointment-reminder` with your Journey ID. The samples use an appointment a week from now and a reminder a day before it.

```javascript Node.js theme={null}
const remindAt = new Date(Date.now() + 6 * 86_400_000).toISOString();
const appointmentAt = new Date(Date.now() + 7 * 86_400_000).toISOString();

const journeysInvokeResponse = await client.journeys.invoke('appointment-reminder', {
  user_id: 'user_123',
  data: {
    appointment_id: 'appt_4Fq9',
    remind_at: remindAt,
    appointment_at: appointmentAt,
  },
  'Idempotency-Key': 'appointment-booked-appt_4Fq9',
});
```

```python Python theme={null}
from datetime import datetime, timedelta, timezone

remind_at = (datetime.now(timezone.utc) + timedelta(days=6)).isoformat()
appointment_at = (datetime.now(timezone.utc) + timedelta(days=7)).isoformat()

journeys_invoke_response = client.journeys.invoke(
    template_id="appointment-reminder",
    user_id="user_123",
    data={
        "appointment_id": "appt_4Fq9",
        "remind_at": remind_at,
        "appointment_at": appointment_at,
    },
    idempotency_key="appointment-booked-appt_4Fq9",
)
```

```bash cURL theme={null}
IN_6D=$(( $(date +%s) + 6 * 86400 )); IN_7D=$(( $(date +%s) + 7 * 86400 ))
REMIND_AT=$(date -u -d "@$IN_6D" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -r "$IN_6D" +%Y-%m-%dT%H:%M:%SZ)
APPOINTMENT_AT=$(date -u -d "@$IN_7D" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -r "$IN_7D" +%Y-%m-%dT%H:%M:%SZ)

curl -X POST https://api.courier.com/journeys/appointment-reminder/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: appointment-booked-appt_4Fq9" \
  -d "{
    \"user_id\": \"user_123\",
    \"data\": {
      \"appointment_id\": \"appt_4Fq9\",
      \"remind_at\": \"$REMIND_AT\",
      \"appointment_at\": \"$APPOINTMENT_AT\"
    }
  }"
```

```ruby Ruby theme={null}
require "time"

remind_at = (Time.now.utc + 6 * 86_400).iso8601
appointment_at = (Time.now.utc + 7 * 86_400).iso8601

journeys_invoke_response = courier.journeys.invoke(
  "appointment-reminder",
  user_id: "user_123",
  data: {
    appointment_id: "appt_4Fq9",
    remind_at: remind_at,
    appointment_at: appointment_at
  },
  idempotency_key: "appointment-booked-appt_4Fq9"
)
```

```go Go theme={null}
remindAt := time.Now().UTC().AddDate(0, 0, 6).Format(time.RFC3339)
appointmentAt := time.Now().UTC().AddDate(0, 0, 7).Format(time.RFC3339)

journeysInvokeResponse, err := client.Journeys.Invoke(
	context.TODO(),
	"appointment-reminder",
	courier.JourneyInvokeParams{
		JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
			UserID: courier.String("user_123"),
			Data: map[string]any{
				"appointment_id":          "appt_4Fq9",
				"remind_at":   remindAt,
				"appointment_at": appointmentAt,
			},
		},
		IdempotencyKey: courier.String("appointment-booked-appt_4Fq9"),
	},
)
```

```java Java theme={null}
String remindAt = java.time.Instant.now().plus(java.time.Duration.ofDays(6)).toString();
String appointmentAt = java.time.Instant.now().plus(java.time.Duration.ofDays(7)).toString();

JourneyInvokeParams params = JourneyInvokeParams.builder()
    .templateId("appointment-reminder")
    .journeysInvokeRequest(JourneysInvokeRequest.builder()
        .userId("user_123")
        .data(JourneysInvokeRequest.Data.builder()
            .putAdditionalProperty("appointment_id", JsonValue.from("appt_4Fq9"))
            .putAdditionalProperty("remind_at", JsonValue.from(remindAt))
            .putAdditionalProperty("appointment_at", JsonValue.from(appointmentAt))
            .build())
        .build())
    .idempotencyKey("appointment-booked-appt_4Fq9")
    .build();
JourneysInvokeResponse journeysInvokeResponse = client.journeys().invoke(params);
```

```php PHP theme={null}
$remindAt = gmdate('Y-m-d\TH:i:s\Z', strtotime('+6 days'));
$appointmentAt = gmdate('Y-m-d\TH:i:s\Z', strtotime('+7 days'));

$journeysInvokeResponse = $client->journeys->invoke(
  'appointment-reminder',
  userID: 'user_123',
  data: [
    'appointment_id' => 'appt_4Fq9',
    'remind_at' => $remindAt,
    'appointment_at' => $appointmentAt,
  ],
  idempotencyKey: 'appointment-booked-appt_4Fq9',
);
```

```csharp C# theme={null}
var remindAt = DateTime.UtcNow.AddDays(6).ToString("o");
var appointmentAt = DateTime.UtcNow.AddDays(7).ToString("o");

JourneyInvokeParams parameters = new()
{
    TemplateID = "appointment-reminder",
    UserID = "user_123",
    Data = new Dictionary<string, JsonElement>()
    {
        { "appointment_id", JsonSerializer.SerializeToElement("appt_4Fq9") },
        { "remind_at", JsonSerializer.SerializeToElement(remindAt) },
        { "appointment_at", JsonSerializer.SerializeToElement(appointmentAt) },
    },
    IdempotencyKey = "appointment-booked-appt_4Fq9",
};

var journeysInvokeResponse = await client.Journeys.Invoke(parameters);
```

```bash CLI theme={null}
IN_6D=$(( $(date +%s) + 6 * 86400 )); IN_7D=$(( $(date +%s) + 7 * 86400 ))
REMIND_AT=$(date -u -d "@$IN_6D" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -r "$IN_6D" +%Y-%m-%dT%H:%M:%SZ)
APPOINTMENT_AT=$(date -u -d "@$IN_7D" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -r "$IN_7D" +%Y-%m-%dT%H:%M:%SZ)

courier journeys invoke \
  --api-key "$COURIER_API_KEY" \
  --template-id appointment-reminder \
  --user-id user_123 \
  --idempotency-key appointment-booked-appt_4Fq9 \
  --data "{\"appointment_id\":\"appt_4Fq9\",\"remind_at\":\"$REMIND_AT\",\"appointment_at\":\"$APPOINTMENT_AT\"}"
```

```text MCP theme={null}
With Courier MCP, start the appointment-reminder journey for user_123 with appointment_id appt_4Fq9, an appointment a week from today, and the reminder 24 hours before it.
```

Send times as UTC ISO 8601 strings. For an appointment booked less than 24 hours out, send a one-off confirmation instead of starting the reminder. The idempotency key makes a retried request return the same run instead of starting a second reminder.

**2. Stop it when the appointment moves**

When an appointment is canceled or rescheduled, call [`POST /journeys/cancel`](https://www.courier.com/docs/api-reference/journeys/cancel-journey-runs) with its token. Pending steps never fire.

```javascript Node.js theme={null}
const cancelJourneyResponse = await client.journeys.cancel({ cancelation_token: 'appt-appt_4Fq9' });
```

```python Python theme={null}
cancel_journey_response = client.journeys.cancel(
    cancelation_token="appt-appt_4Fq9",
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys/cancel \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelation_token": "appt-appt_4Fq9"
  }'
```

```ruby Ruby theme={null}
cancel_journey_response = courier.journeys.cancel(cancel_journey_request: {cancelation_token: "appt-appt_4Fq9"})
```

```go Go theme={null}
cancelJourneyResponse, err := client.Journeys.Cancel(context.TODO(), courier.JourneyCancelParams{
	CancelJourneyRequest: courier.CancelJourneyRequestUnionParam{
		OfByCancelationToken: &courier.CancelJourneyRequestByCancelationTokenParam{
			CancelationToken: "appt-appt_4Fq9",
		},
	},
})
```

```java Java theme={null}
CancelJourneyRequest.ByCancelationToken params = CancelJourneyRequest.ByCancelationToken.builder()
    .cancelationToken("appt-appt_4Fq9")
    .build();
CancelJourneyResponse cancelJourneyResponse = client.journeys().cancel(params);
```

```php PHP theme={null}
$cancelJourneyResponse = $client->journeys->cancel(
  cancelationToken: 'appt-appt_4Fq9'
);
```

```csharp C# theme={null}
JourneyCancelParams parameters = new()
{
    CancelJourneyRequest = new ByCancelationToken("appt-appt_4Fq9")
};

var cancelJourneyResponse = await client.Journeys.Cancel(parameters);
```

```bash CLI theme={null}
courier journeys cancel \
  --api-key "$COURIER_API_KEY" \
  --cancelation-token appt-appt_4Fq9
```

```text MCP theme={null}
With Courier MCP, cancel the journey runs with the cancelation token appt-appt_4Fq9.
```

For a reschedule, cancel first, then start a new run with the new times. Include the new time in the idempotency key, such as `appointment-booked-appt_4Fq9-2026-12-03T17:30`, so the new request doesn't return the canceled run.

## Verify

**1. Run it on a short clock**

Duplicate the Journey for testing, set the copy's 30-minute delay to 2 minutes, and change its cancelation token to `appt-test-{{data.appointment_id}}`. Publish the copy and invoke it for a test patient with `remind_at` a few minutes from now.

**2. Follow the run**

Open the Journey's **Logs** tab and select the run. Click a node to see its input, the conditions it evaluated, and its output. Open the SMS message and confirm the text has the time and the link, and nothing clinical.

**3. Check the email fallback**

Invoke the copy for a test patient with an invalid phone number. The SMS doesn't reach `DELIVERED`, and the email goes out.

**4. Check the opt-out**

Opt the test patient out of **Appointment reminders** and invoke again. Both sends end as `FILTERED` with the reason `UNSUBSCRIBED`.

**5. Confirm a cancel stops the run**

Invoke once more, then cancel with the test token while the run waits at the first delay. The run reads **Canceled** in the **Logs** tab.

## FAQ

> [accordion] Can the reminder include the reason for the visit?
>
> The reason for a visit is protected health information, and a text shows on lock screens and shared phones. Keep it in your app behind sign-in. See [HIPAA and BAAs](https://www.courier.com/docs/security/hipaa.md).

> [accordion] How do I add a second reminder an hour before?
>
> Add another `Until` delay on a second field, such as `remind_1h_at`, followed by a second SMS node. The [appointment reminder recipe](https://www.courier.com/recipes/appointment-reminder-sms) has both reminders, ready to copy.
