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

# Channels

> Learn how to set up email and push notifications so Trophy can reach your users.

Agents send messages over two channels, email and push notifications. They pick the channel that works best for each user, based on how that user engages and which channels the user has chosen in their [preferences](https://docs.trophy.so/agentic-messaging/user-preferences.md).

Both channels are managed on the [Channels](https://app.trophy.so/agentic-messaging/channels) page under **Agentic messaging** in the Trophy dashboard, which has an **Emails** tab and a **Push** tab.

> [!NOTE]
>
> Channels are shared across Trophy. The domain and push providers you set up
> here are also used by [legacy emails](https://docs.trophy.so/features/emails.md) and [legacy push
> notifications](https://docs.trophy.so/features/push-notifications.md), so you only need to set them up
> once.

## Email

Trophy sends email from your own domain, with your [branding](https://docs.trophy.so/context/brand-kit.md#branding).

To send email, Trophy needs:

**1. A verified sending domain**

Verify your domain on the **Emails** tab. See [domain
verification](#domain-verification) below.

**2. An email address for each user**

Set the `email` attribute when you [identify
users](https://docs.trophy.so/data-sources/users.md#identifying-users). Users without an email address, or
who have unsubscribed, aren't sent emails.

### Domain verification

Trophy supports sending emails from your own domain out-of-the-box. There are two ways to set this up, Single Sender Verification and DNS Verification.

All domain settings are on the **Emails** tab of the [Channels](https://app.trophy.so/agentic-messaging/channels) page in the Trophy dashboard.

> [!TIP]
>
> If you're looking to get set up quickly we recommend starting with Single
> Sender Verification then setting up DNS Verification when you're ready to move
> to production.

> [card] [Sender Verification](#sender-verification-basic)
>
> Quickly verify a single email address

> [card] [DNS Verification](#dns-verification-advanced)
>
> Recommended for production use

#### Sender verification (basic)

Sender Verification is a quick way to verify a single email address that you want to use with Trophy without needing to change any code or DNS settings.

Enter the email address, from name and reply-to email that you'd like Trophy to use when sending emails:

![](https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/emails/sender_verification.jpg?fit=max\&auto=format\&n=vvlxkggAvglghNGz\&q=85\&s=a33a14507303b2a2c73f444aa2c65348)

Trophy will send a verification email to that address. Simply click the link in the email to let Trophy know that you own the address and you'll be good to go.

> [!NOTE]
>
> The email you receive will come from our email provider, Postmark. So keep an
> eye out for 'Postmark Support' in your inbox!

Sender Verification is great for getting started but is limited in that you won't benefit from your existing email reputation and can only send emails from one address.

Also, if you want to change the address in the future, you'll have to go through Sender Verification again on the **Emails** tab of the [Channels](https://app.trophy.so/agentic-messaging/channels) page.

#### DNS verification (advanced)

For production use we recommend DNS Verification. Once set up, this allows you to configure Trophy to send emails from any address on your domain. So if you want to change the address in future, you won't need to verify again.

Completing DNS verification also gives you the full benefits of any existing domain reputation and is the best way to make sure your emails avoid the spam folder.

This does however require adding a couple of new entries into your DNS to allow Trophy to verify you own the domain.

Follow the steps below to set up DNS verification:

**1. Head to the Channels page**

Open the **Emails** tab of the [Channels](https://app.trophy.so/agentic-messaging/channels) page. This is where you'll configure everything related to the email domain Trophy will use to send emails on your behalf.

**2. Configure your domain**

Head down to the DNS Verification section and enter the domain you want to set up with Trophy.

You can also configure a custom Return Path. This is where Trophy will forward notifications of bounced emails to help you investigate deliverability issues:

![](https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/emails/dns-verification-1.png?fit=max\&auto=format\&n=vvlxkggAvglghNGz\&q=85\&s=9e2190791802e9273fc6151a01fa726e)

**3. Set up your DNS records**

Once you've entered your email domain, Trophy will provide you with details for two new DNS records that you'll need to add to your DNS provider.

![](https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/emails/dns-verification-2.png?fit=max\&auto=format\&n=vvlxkggAvglghNGz\&q=85\&s=14b25c189b0a2bfd350520b200e39946)

* First is the **DKIM** record which is used by inbox providers like Google to verify the authenticity of emails. Enter the name and value provided as a new **TXT** record in your DNS provider.
* Second is the **Return Path** record. This is used to forward notifications of email bounces to your domain. Enter the name and value provided as a new **CNAME** record in your DNS provider.

Here are the pages for the most common DNS providers on how to set up new records:

> [accordion] GoDaddy
>
> [Add a TXT record](https://www.godaddy.com/en-uk/help/add-a-txt-record-19232)
> [Add a CNAME record](https://www.godaddy.com/en-uk/help/add-a-cname-record-19236)

> [accordion] Cloudflare
>
> [Add DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records)

> [accordion] NameCheap
>
> [Add a CNAME record](https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain/)
> [Add a TXT record](https://www.namecheap.com/support/knowledgebase/article.aspx/317/2237how-do-i-add-txtspfdkimdmarc-records-for-my-domain/#:~:text=this%20guide%20.-,DKIM%20records,-DKIM%20\(DomainKeys%20Identified\))

> [!WARNING]
>
> Note: If you're using a proxy like Cloudflare, make sure to turn  it off for these records or Trophy won't be able to properly verify them.

**4. Verify DNS records**

Once you've added the two records into your DNS settings, click the refresh icon and Trophy will attempt to verify the records for you.

Usually Trophy can verify records within a few minutes but bear in mind that DNS changes can take up to a few hours to fully propagate.

If you see the following alert, the records may not have propagated yet, or there may be an issue with your setup.

![](https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/emails/dns-verification-3.png?fit=max\&auto=format\&n=vvlxkggAvglghNGz\&q=85\&s=9136cf66e699a6ac277286625a07fd77)

Once you're sure everything's set up correctly in your DNS provider, click refresh and Trophy will attempt to verify your DNS records once again.

As soon as you see the following message, you know everything's verified:

![](https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/emails/dns-verification-4.png?fit=max\&auto=format\&n=vvlxkggAvglghNGz\&q=85\&s=f9a641ceaadc0b85a8bfc525de65aa65)

**5. Configure your sending address**

Once your DNS records are verified, it's time to choose the email address you want to send emails from. Note that now you've fully verified your domain, you can change this address whenever you like without impacting deliverability.

Simply enter the email address you want Trophy to send from, the name to show to users in the inbox when they receive emails and a support email address they can use to contact you if needed:

![](https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/emails/dns-verification-5.png?fit=max\&auto=format\&n=vvlxkggAvglghNGz\&q=85\&s=20109f6d629f814d5318a7d08555076f)

## Push notifications

Trophy delivers push notifications natively through your own push setup.

To send push notifications, Trophy needs:

**1. A configured push provider**

Add your provider's credentials on the **Push** tab. See [supported
providers](#supported-channels) below.

**2. Device tokens for each user**

Associate device tokens with each user when you identify them or send metric
events. See [device tokens](#device-tokens) below.

### Supported providers

Trophy supports sending push notifications through 3 providers, which can all be configured on the **Push** tab of the [Channels](https://app.trophy.so/agentic-messaging/channels/push) page in the Trophy dashboard.

#### Apple Push Notification Service (APNs)

Trophy supports sending push notifications to users via APNs through a certificate-based connection.

To send push notifications using APNs, you'll need to provide Trophy with the following credentials from your Apple Developer Account:

* **APN Signing Key**: Trophy uses this to securely send notifications via APNs
* **Team ID**: The team ID of your Apple Developer Account
* **Key ID**: The ID of your APNs authentication key
* **Bundle ID**: Your app's unique bundle identifier

> [!NOTE]
>
> For more information on how to configure certificate-based connection to APNs
> from a third-party service, read the [official setup
> guide](https://developer.apple.com/documentation/usernotifications/establishing-a-certificate-based-connection-to-apns).

#### Firebase Cloud Messaging (FCM)

Trophy supports sending push notifications to users via FCM. To achieve this you'll need to provide Trophy with your Firebase Service Account JSON in the following format:

```json FCM Service Account JSON theme={null}
{
  "type": "service_account",
  "project_id": "XXX",
  "private_key_id": "XXX",
  "private_key": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n",
  "client_email": "XXX@XXX.com",
  "client_id": "XXX",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/XXX"
}
```

> [!NOTE]
>
> For more information on Firebase service accounts and how to authenticate
> external services to use FCM, read the [official service accounts
> guide](https://firebase.google.com/support/guides/service-accounts).

#### Expo Push Service

Trophy supports sending push notifications to users via Expo Push Service.

Expo Push Service saves you having to integrate with FCM and APNs individually and automatically directs notifications through the relevant service based on your users platform.

To achieve this you must provide Trophy with a few key details from your Expo account:

* **Expo Project Name**: The name of your Expo project
* **Expo Push Token**: Your authentication token for sending notifications via Expo (required if using [enhanced security](https://docs.expo.dev/push-notifications/sending-notifications/#additional-security)).

> [!NOTE]
>
> For more information on Expo Push Service and how to authenticate external
> providers, see the [official
> guide](https://docs.expo.dev/push-notifications/sending-notifications).

### Device tokens

To send notifications to users, Trophy needs to know the unique tokens assigned to their devices. You tell Trophy about devices by associating device tokens with each user you identify.

Trophy will use the device tokens you associate with each user when communicating with your [push provider](#supported-channels) to route notifications to the correct device.

To associate a device token with a user in Trophy, either assign `deviceTokens` when [identifying users explicitly](https://docs.trophy.so/api-reference/endpoints/users/identify-a-user.md), or when [sending metric events](https://docs.trophy.so/api-reference/endpoints/events/submit-a-metric-event.md).

Here's how to associate device tokens when identifying users:

```bash cURL {10} theme={null}
curl --request PUT \
  --url https://app.trophy.so/api/users/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "email": "user@example.com",
  "name": "User",
  "tz": "Europe/London",
  "subscribeToEmails": true,
  "deviceTokens": ["token1", "token2"]
}'
```

```typescript Node {6} theme={null}
trophy.users.identify("user-id", {
  email: "user@example.com",
  name: "User",
  tz: "Europe/London",
  subscribeToEmails: true,
  deviceTokens: ["token1", "token2"],
});
```

```python Python {7} theme={null}
client.users.identify(
    id="user-id",
    email="user@example.com",
    name="User",
    tz="Europe/London",
    subscribeToEmails=True,
    deviceTokens=["token1", "token2"],
)
```

```php PHP {6} theme={null}
$trophy->users->identify("user-id", [
    'email' => 'user@example.com',
    'name' => 'User',
    'tz' => 'Europe/London',
    'subscribeToEmails' => true,
    'deviceTokens' => ['token1', 'token2'],
]);
```

```java Java {6} theme={null}
UpdatedUser user = UpdatedUser.builder()
    .email("user@example.com")
    .name("User")
    .tz("Europe/London")
    .subscribeToEmails(true)
    .deviceTokens(Arrays.asList("token1", "token2"))
    .build();

client.users().identify("user-id", user);
```

```go Go {8} theme={null}
response, err := client.Users.Identify(
    "user-id",
    &api.UpdatedUser{
        Email:            "user@example.com",
        Name:             "User",
        Tz:               "Europe/London",
        SubscribeToEmails: true,
        DeviceTokens:     []string{"token1", "token2"},
    },
)
```

```csharp C# {6} theme={null}
var user = new UpdatedUser {
    Email = "user@example.com",
    Name = "User",
    Tz = "Europe/London",
    SubscribeToEmails = true,
    DeviceTokens = new[] { "token1", "token2" }
};

await trophy.Users.IdentifyAsync("user-id", user);
```

```ruby Ruby {7} theme={null}
result = client.users.identify(
  "user-id",
  :email => "user@example.com",
  :name => "User",
  :tz => "Europe/London",
  :subscribeToEmails => true,
  :deviceTokens => ["token1", "token2"]
)
```

And here's how to associate device tokens when sending metric events:

```bash cURL {10} theme={null}
curl -X POST https://app.trophy.so/api/metrics/flashcards-flipped/event \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18",
    "email": "user@example.com",
    "tz": "Europe/London",
    "deviceTokens": ["token1", "token2"]
  },
  "value": 750
}'
```

```typescript Node {6} theme={null}
trophy.metrics.event("flashcards-flipped", {
  user: {
    id: "18",
    email: "user@example.com",
    tz: "Europe/London",
    deviceTokens: ["token1", "token2"],
  },
  value: 750,
});
```

```python Python {7} theme={null}
client.metrics.event(
    key="flashcards-flipped",
    user=EventRequestUser(
        id="18",
        email="user@example.com",
        tz="Europe/London",
        deviceTokens=["token1", "token2"],
    ),
    value=750.0,
)
```

```php PHP {6} theme={null}
$user = new EventRequestUser([
    'id' => '18',
    'email' => 'user@example.com',
    'deviceTokens' => ['token1', 'token2'],
]);

$request = new MetricsEventRequest([
    'user' => $user,
    'value' => 750
]);

$trophy->metrics->event("flashcards-flipped", $request);
```

```java Java {6} theme={null}
MetricsEventRequest request = MetricsEventRequest.builder()
      .user(
        EventRequestUser.builder()
          .id("18")
          .email("user@example.com")
          .deviceTokens(Arrays.asList("token1", "token2"))
          .build()
      )
      .value(750)
      .build();

EventResponse response = client.metrics().event("flashcards-flipped", request);
```

```go Go {8} theme={null}
response, err := client.Metrics.Event(
    "flashcards-flipped",
    &api.MetricsEventRequest{
        User: &api.EventRequestUser{
            Id: "18",
            Email: "user@example.com",
            DeviceTokens: []string{"token1", "token2"},
        },
        Value: 750,
    },
)
```

```csharp C# {6} theme={null}
var user = new EventRequestUser {
   Id = "18",
   Email = "user@example.com",
   DeviceTokens = new[] { "token1", "token2" }
};

var request = new MetricsEventRequest {
   User = user,
   Value = 750
};

await trophy.Metrics.EventAsync("flashcards-flipped", request);
```

```ruby Ruby {7} theme={null}
result = client.metrics.event(
  :key => 'flashcards-flipped',
  :user => {
    :id => '18',
    :email => 'user@example.com',
    :deviceTokens => ['token1', 'token2']
  },
  :value => 750
)
```

> [!TIP]
>
> Each user can have multiple device tokens associated with them, to support
> users who use multiple devices.

## Reachable users

Agents only consider users they can reach on at least one channel. A user with an email address but no device tokens only receives email, and a user with device tokens but no email address only receives push.

Set up both channels to give agents the most room to pick the right one for each user.

## Get support

Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.