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
| Field | Type | Required | Notes |
|---|---|---|---|
| string | yes | Valid email address; normalized to lowercase | |
| list_id | number | yes | Target recipient list |
| name | string | no | — |
| first_name | string | no | — |
| last_name | string | no | — |
| company | string | no | — |
| phone | string | no | — |
| status | "active" | "inactive" | "unsubscribed" | "suppressed" | "bounced" | "invalid" | no | Default: "active" |
| source | "manual" | "import" | "crm" | "mixed" | no | Default: "manual" |
| person_id | number | no | CRM person reference |
| metadata | object | no | — |
Bulk delete recipients.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| ids | number[] | yes | IDs to delete |
Get a recipient by ID.
- Params
- id (int)
Update a recipient. Only provided fields are changed.
- Params
- id (int)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| string | no | Normalized to lowercase | |
| name | string | no | — |
| status | "active" | "inactive" | "unsubscribed" | "suppressed" | "bounced" | "invalid" | no | — |
| source | "manual" | "import" | "crm" | "mixed" | no | — |
| person_id | number | no | — |
Delete a single recipient.
- Params
- id (int)