Logotipo Hedhog

Get Hedhog updates in your inbox

New releases, fresh recipes, and breaking changes — no spam.

Campaign Submodule

recipients

Direct CRUD over individual campaign_recipient records across all lists.

Source path: libraries/campaign/src/services/campaign-recipient.service.ts

Module file: campaign.module.ts

Introduction

The Recipients submodule exposes flat, list-agnostic CRUD over `campaign_recipient` rows through CampaignRecipientService — a lighter-weight counterpart to the recipient-management endpoints nested under Recipient Lists. Where the recipient-lists submodule manages recipients in the context of a specific list (bulk import, CRM sync, public signup, list counter recalculation), this submodule is for direct, single-record access: looking up, editing, or removing one recipient by its own ID regardless of which list it belongs to.

Creating a recipient here still requires a `list_id` and upserts by email within that list, mirroring the same uniqueness rule enforced elsewhere (one recipient row per email per list). Updates allow changing the status — including the terminal/blocking statuses `unsubscribed`, `suppressed`, `bounced`, and `invalid` that CampaignDispatchService and CampaignEmailWorkerService check before including a recipient in a send. Email values are normalized to lowercase on both create and update so that lookups and deduplication remain case-insensitive throughout the module.

Unlike the recipient-lists submodule's recipient endpoints, this submodule does not call `recalculateCounters()` on the owning list after create/update/delete — callers that need the list's rolled-up counts to reflect a change made through this submodule should expect a slight staleness until the next list-level recipient mutation triggers a recalculation.

HTTP Endpoints

6 endpoints

Paginated list of all recipients across all lists.

Query
page, pageSize, search, status

Create a recipient and assign to a list. Upserts by email within the list.

Body

FieldTypeRequiredNotes
emailstringyesValid email address; normalized to lowercase
list_idnumberyesTarget recipient list
namestringno
first_namestringno
last_namestringno
companystringno
phonestringno
status"active" | "inactive" | "unsubscribed" | "suppressed" | "bounced" | "invalid"noDefault: "active"
source"manual" | "import" | "crm" | "mixed"noDefault: "manual"
person_idnumbernoCRM person reference
metadataobjectno

Bulk delete recipients.

Body

FieldTypeRequiredNotes
idsnumber[]yesIDs to delete

Get a recipient by ID.

Params
id (int)

Update a recipient. Only provided fields are changed.

Params
id (int)

Body

FieldTypeRequiredNotes
emailstringnoNormalized to lowercase
namestringno
status"active" | "inactive" | "unsubscribed" | "suppressed" | "bounced" | "invalid"no
source"manual" | "import" | "crm" | "mixed"no
person_idnumberno

Delete a single recipient.

Params
id (int)