> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Shipment Notifications via Perform.AI

> Set up automated email and SMS shipment update notifications in Perform.AI using the notification_email and notification_phone fields.

Perform.AI can automatically send shipment update emails and SMS messages to your customers as their parcels move through the delivery journey. You control exactly who receives these notifications by including the `notification_email` and `notification_phone` fields when you create or update a shipment.

## Notification Fields

There are two dedicated fields for configuring notifications on a shipment:

### `notification_email`

An array of email addresses that will receive automated shipment update emails from Perform.AI. You can include multiple addresses — for example, the customer's address and a support alias.

* **Type:** Array of strings (email address format)
* **Max length per address:** 100 characters
* **Example:** `["customer@email.com", "support@shop.com"]`

### `notification_phone`

An array of phone numbers that will receive automated SMS updates from Perform.AI. Provide each number in the format `+{country_code}{number}` — for example, `+6512345678` for a Singapore number.

* **Type:** Array of strings
* **Max length per number:** 50 characters
* **Format:** `+{country_code}{number}`, e.g. `+6512345678`

Perform.AI automatically normalizes common phone number variations. For example, `"06512345678"`, `"00651-234-567-8"`, `"+65123-456-78"`, and `"65 123 456 (78)"` are all stored as `"+6512345678"`.

<Warning>
  Email and phone numbers stored in address objects — such as
  `recipient_address.email`, `sender_address.phone`, `to_address.email`,
  `from_address.phone`, or `return_address.email` — do **not** receive
  notifications. Only the `notification_email` and `notification_phone` arrays
  are used by Perform.AI to send shipment update emails and SMS messages.
</Warning>

## Example: Setting Notification Fields on a Shipment

Include `notification_email`, `notification_phone`, and optionally `tracking_page_reference` in your shipment create or update payload:

```json theme={null}
{
  "notification_email": ["customer@email.com", "support@shop.com"],
  "notification_phone": ["+6512345678"],
  "tracking_page_reference": "your-tracking-page-ref"
}
```

## Updating Notifications

When you send an update request for an existing shipment that includes `notification_email` or `notification_phone`, the values you provide **overwrite** the existing lists entirely. If you want to keep previously stored addresses or numbers, you must re-include them in the updated array alongside any new additions.

## Linking Notifications to a Tracking Page

Combine the notification fields with `tracking_page_reference` to give your customers a seamless branded experience. When you link a shipment to a tracking experience:

* Notification emails and SMS messages adopt the design and branding from that tracking page.
* Tracking links in notification emails open your branded tracking page rather than a generic carrier portal.

See [Tracking Pages](/guides/tracking-page) for more detail on how to configure and use the `tracking_page_reference` field.

<Tip>
  Add both `notification_email` and `notification_phone` to maximize customer
  reach for delivery updates. Customers who prefer SMS over email — or vice
  versa — will still receive timely updates about their shipment.
</Tip>