Recipient Lists — User Guide

Recipient Lists are reusable contact collections used to populate marketing broadcasts. Build a list once — from your CRM, from an Excel file, or by hand — and reuse it across any number of campaigns.

When to use a recipient list

• You have a group of contacts you message repeatedly (e.g. "VIP Customers", "Past staycation buyers", "Summer 2026 interest list").
• You want to prepare the audience for a broadcast ahead of time instead of building it fresh every send.
• You want to import a contact list you received from outside TQPro (Excel/CSV).

Every list is single-channel — either WhatsApp or Email. Create separate lists for each channel even if the contacts overlap, because the matching key differs (phone vs. email).

Getting there

Two entry points:

• Main header → Engagement → Recipient Lists
• Campaign Planning page (mktplan.html) → the list icon in the toolbar above the campaign tree

The hub page shows all active lists with a channel badge, member count, and actions.

Creating a list

1. Click + New List.
2. Enter a name. Keep it descriptive — this is what you'll see in the broadcast composer.
3. Pick the channel (WhatsApp or Email). You cannot change the channel later; create a new list if you need the other channel.
4. Optional: add a description.
5. Save.

The new list starts empty. You'll land back on the hub; click the list name or the people icon in the row to open it and start adding members.

Adding members

On the list detail page, four ways to get contacts in:

1. Populate from CRM

The fastest way to get started. Click Populate from CRM — a small dialog opens with an optional filter.

What happens:

• Clears all existing members on the list.
• Fetches every customer from CRM.
• For WhatsApp lists: phone is normalized to international format — +X… is kept as-is, 00X… is converted to +X…, and anything without a + or 00 prefix is dropped (no country context).
• For Email lists: email is lowercased; customers with doNotEmail = true are excluded.
• Dedupes by contact value.

Optional prefix filter. The filter is applied after normalization, so you write it in the output form:

Example use	Mode	Prefix
UAE-only WhatsApp list	Include	+971
Non-UAE list	Exclude	+971
Gmail-only email list	Include	(not a prefix — use the @ later, emails are awkward to prefix-filter)

Leave the prefix empty to include everything. The modal shows a help hint based on the list's channel.

After populate, a toast shows the breakdown:

122 added of 1403 customers · 890 no contact · 261 invalid format · 130 filtered out

The same numbers are logged server-side. Open the browser console for the full response payload.

2. Import from Excel

Click Import and pick a .xlsx file. Columns required in the header row:

Column	Notes
Name	Display name
Phone	Required for WhatsApp lists (E.164 format recommended, e.g. +971501234567)
Email	Required for Email lists
Language	Optional — en, ar, ru, hi, sr

• Max file size 5 MB, max 5000 rows.
• Upsert semantics: existing members matched by phone (WhatsApp) or email (Email) are updated; new rows inserted.
• You'll see a summary: X added, Y updated, Z failed. Open the browser console to see the per-row error list.

Click Export to download the current list as .xlsx. An empty list returns a template with two sample rows for the right channel — handy as a starting point.

3. Add a member manually

Click + Add Member, fill in the fields, save. Phone is required for WhatsApp lists; email is required for Email lists. Email is automatically lowercased and validated.

4. Edit or remove existing members

Each row has a pencil (edit) and trash (remove) button. Clear All empties the list but keeps it active.

Using a list in a broadcast

Recipient lists feed into broadcasts in two places:

From a broadcast activity (Campaign Planning page)

1. Open the activity inside a WhatsApp or Email broadcast campaign.
2. In the Broadcast Configuration panel, click Add from List.
3. Check one or more lists, click Add Selected.
4. Members are copied into the activity's recipient table with dedupe — contacts already in the activity are skipped.

You can mix lists freely; picking the same list twice just no-ops because of dedupe.

From the Broadcast Composer (broadcast-compose.html)

Step 2 of the composer ("Recipients") shows all active WhatsApp lists as checkboxes with their member counts. Tick the ones you want; the estimated recipient count updates as a running total.

What happens to opt-outs

Opt-outs are not filtered when you build a list. A list is a snapshot of who could be contacted — it stays stable even as people opt out.

Opt-outs are re-checked the moment you copy a list into a broadcast. Opted-out contacts still appear in the broadcast's recipient table, but marked OPTED_OUT so they are skipped at send time (and so you can see they were known-opted-out when you assembled the list).

This means:

• You don't need to rebuild a list because someone opted out.
• Staff can see at a glance which of the intended recipients were blocked.

Editing recipients after the copy

Copying from a list is a one-way snapshot into the activity. You can still add, edit, remove, or Excel-round-trip recipients on the activity itself after that point — the activity's recipient list is independent once built.

This matters when an activity needs last-minute tweaks that shouldn't affect the source list.

Deleting a list

Delete soft-removes a list (sets active = false). Members are preserved in the database for audit, but the list no longer appears in the hub or the broadcast composer. Contact an admin if you need a list brought back.

Tips

• Name your lists for the audience, not the campaign — "VIP guests" survives across many campaigns; "Summer 2026 blast" rots after one.
• Keep one list per channel, per audience. Don't try to cram WhatsApp and Email into the same list.
• Import from Excel when you have data that isn't in CRM yet (e.g. trade-show attendees, event RSVPs). Importing into a fresh list keeps CRM clean of unverified contacts.
• Use Export + re-Import as a bulk-edit tool. Download, edit in Excel, upload — the upsert keeps member IDs stable.

See also

• Recipient Lists — feature overview
• Broadcast feature overview