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

# Example app: weekly email with custom_data

> How the Clean Beans example app sends a weekly email report personalized per recipient with custom_data and Liquid, and how Data Feeds compare.

This page is part of [Example app: a full OneSignal integration](https://documentation.onesignal.com/docs/en/example-full-integration-overview.md), which follows one real app from end to end. The app is **Clean Beans**, a cleaning rota for shared homes, built with Expo (React Native) and a Supabase backend.

Every Sunday, each household gets an email recapping its week: sessions, tasks, minutes, a leaderboard, and each person's own numbers.

![The Clean Beans weekly report email](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-email.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=386b96883e6b7af79d0406d4095f73c7)

The weekly report: household totals, your own week, and the leaderboard.

The interesting problem is personalization. Everyone in a household sees the same leaderboard, but each person should see their own name and stats. Sending one request per person would work, but there is a better way.

## One request per household, personalized per person

The function sends **one** request per household. It passes all the data in `custom_data`, including a `users` object keyed by External ID. The template then picks out the right entry for whoever it is rendering for.

```typescript supabase/functions/weekly-report/index.ts theme={null}
const customData = {
  household_name: householdNames[householdId] || 'Your Household',
  week_label: weekLabel,
  household_sessions: String(householdSessions.length),
  household_tasks: String(totalTasks),
  household_mins: String(totalMins),
  top_room: topRoom,
  leaderboard,
  users,
};

    // ...

const onesignalPayload: Record<string, unknown> = {
  app_id: ONESIGNAL_APP_ID,
  template_id: ONESIGNAL_WEEKLY_TEMPLATE_ID,
  include_aliases: {
    external_id: externalIds,
  },
  target_channel: 'email',
  custom_data: customData,
};
```

In the template, one line of Liquid selects the current recipient's data.

```liquid email-templates/weekly-report.html theme={null}
{% assign user = message.custom_data.users[subscription.external_id] %}
{% assign lb = message.custom_data.leaderboard %}
```

After that, `user` holds this person's stats, and anything read from `message.custom_data` directly is shared by the household.

```liquid email-templates/weekly-report.html theme={null}
Hey {{ user.name | default: "there" }}! 👋
Here's how <strong>{{ message.custom_data.household_name | default: "your household" }}</strong> did this week.

{% for member in lb %}
  {% if forloop.index == 1 %}🥇{% elsif forloop.index == 2 %}🥈{% elsif forloop.index == 3 %}🥉{% else %}{{ forloop.index }}{% endif %}
  {{ member.name }}{% if member.name == user.name %} (you){% endif %}
{% endfor %}
```

> [!NOTE]
>
> The second Liquid example is simplified from the template to show the logic without the table markup.

## Stay inside the size limit

`custom_data` for email is limited to 10 KB. A large household could exceed that, so the function measures the payload and trims the leaderboard if it has to.

```typescript supabase/functions/weekly-report/index.ts theme={null}
// Check payload size (10KB limit for email)
const payloadSize = new TextEncoder().encode(JSON.stringify(customData)).length;
if (payloadSize > 10000) {
  console.warn(`Household ${householdId} custom_data is ${payloadSize} bytes (over 10KB limit). Trimming leaderboard.`);
  customData.leaderboard = customData.leaderboard.slice(0, 5);
}
```

## Schedule and preferences

A weekly schedule calls the function every Sunday at 09:00 UTC, using the same `pg_cron` pattern as the push reminders with the expression `0 9 * * 0`. Only users with **Weekly Email Summary** switched on are included.

**Dashboard setup.** In **Messages > Templates**, create an email template, paste in the HTML, and copy the template ID into your backend's secrets. `custom_data` only works with a template, so `template_id` is required.

## The alternative: Data Feeds

There is a second way to get per-person data into an email, and Clean Beans chose not to use it. It is worth understanding, because for some apps it is the better fit.

With `custom_data`, your backend **pushes** the data to OneSignal when it sends. With a **Data Feed**, OneSignal **pulls** the data from your API at the moment each email is sent. The send itself is started by a Journey, not by your backend.

> [!NOTE]
>
> The examples in this subsection are illustrative. They show how the weekly report would have been built with a Data Feed. They are not taken from the app.

Here is how the weekly report would have worked.

**1. Expose an endpoint that returns one person's week**

A backend function takes a user ID and returns that user's stats and their household's leaderboard as JSON.

```json Response from your API theme={null}
{
  "name": "George",
  "household_name": "The Smiths",
  "week_label": "Nov 10 – Nov 16",
  "sessions": 5,
  "tasks": 19,
  "mins": 63,
  "streak": 24,
  "leaderboard": [
    { "name": "George", "sessions": 5, "mins": 63 },
    { "name": "Jonny", "sessions": 4, "mins": 52 }
  ]
}
```

**2. Create the Data Feed in the dashboard**

In **Settings > Data feeds**, give the feed an alias and point it at the endpoint. The URL and headers accept Liquid, so the recipient's External ID can be passed in.

```text Data Feed configuration theme={null}
Alias:   weekly
Method:  GET
URL:     https://YOUR_PROJECT_REF.supabase.co/functions/v1/weekly-stats?user_id={{ external_id }}
Headers: { "Authorization": "Bearer YOUR_FEED_SECRET" }
```

**3. Attach the feed to the email template and read from it**

In the template, values come from `data_feed`, followed by the alias.

```liquid Email template theme={null}
Hey {{ data_feed.weekly.name | default: "there" }}!
Here's how {{ data_feed.weekly.household_name }} did this week.

{% for member in data_feed.weekly.leaderboard %}
  {{ member.name }}: {{ member.sessions }} sessions
{% endfor %}
```

**4. Send it from a recurring Journey**

A Journey with a time window of Sunday morning as its first step, and a re-entry rule, sends the template every week. No schedule or send code lives in your backend.

### Which one to use

| | `custom_data` (what Clean Beans uses) | Data Feeds |
| - | - | - |
| Who starts the send | Your backend, by calling the API | A Journey in the dashboard |
| When the data is read | When your backend builds the request | When each message is sent |
| Requests for a household of four | One request to OneSignal | Four calls from OneSignal to your API |
| Channels | Push, email, and SMS | Email and SMS, inside Journeys only |
| Size limit | 10 KB for email | Responses of up to about 50 KB are recommended |
| If the data is missing | Your code decides what to do | That recipient gets no message |
| Changing the schedule or flow | A backend change | A dashboard change |
| Your API's exposure | Nothing is exposed | A public endpoint you must secure and keep fast |

**Choose `custom_data` when your backend is already the thing that decides to send.** That is the case for the weekly report. The backend runs on a schedule, knows which households opted in, and has every number in hand, so passing the data along costs nothing extra. One request covers a whole household, there is no endpoint to protect, and a failure shows up in your own logs. The price is that timing and audience live in code, and the payload has a fixed size limit.

**Choose a Data Feed when the send belongs to a Journey.** A Journey decides for itself when to message someone, days after an event or once a wait condition is met, and your backend is not there to supply data at that moment. A Data Feed fills that gap, and it means the people who run messaging can change the schedule, add a branch, or test variants without a deploy. The price is that your API is called once per recipient and should answer in about a quarter of a second, each template can use only one feed, and a failed call means that person silently gets nothing.

For Clean Beans the deciding factors were simple. The backend already had the data and the schedule, the leaderboard is shared by a household so one request is far cheaper than one call per person, and preferences are stored in the app's database, where the backend can check them directly.

> [card] [Personalize with custom\_data](https://documentation.onesignal.com/docs/en/personalization-api-custom-data.md)
>
> Size limits and Liquid access patterns.

> [card] [Data feeds](https://documentation.onesignal.com/docs/en/data-feeds.md)
>
> Pull live data into Journey emails and SMS.

> [card] [Using Liquid syntax](https://documentation.onesignal.com/docs/en/using-liquid-syntax.md)
>
> Filters, loops, and conditions.


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