Segments and Topics
Relevant source files
The following files were used as context for generating this wiki page:
Segments and Topics allow you to organize and categorize audience members for targeted communication. Segments group contacts based on specific criteria, while Topics manage subscription preferences for different types of content, such as newsletters or product updates. Sources: src/Service/Segment.php, src/Service/Topic.php
The Resend PHP SDK provides a structured way to manage these resources through dedicated service classes. These services interact with the Resend API to create, retrieve, update, and delete segments and topics, as well as manage the relationships between these resources and individual contacts. Sources: src/Service/Contacts/Segment.php, src/Service/Contacts/Topic.php
Topics
Topics represent specific categories of communication that contacts can subscribe to or unsubscribe from. Each topic maintains a default subscription preference that applies to new contacts. Sources: src/Topic.php:12
Topic Data Model
The Topic resource contains the following fields:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the topic. |
name | string | The name of the topic. |
description | string | A detailed description of the topic's purpose. |
default_subscription | string | Default preference for new contacts (opt_in or opt_out). |
object | string | The type of object (always topic). |
Sources: src/Topic.php:7-14, tests/Fixtures/Topic.php:5-11
Topic Service Operations
The Resend\Service\Topic class provides methods to manage topics globally within the account.
The diagram shows the available operations in the Topic service and their corresponding API endpoints. Sources: src/Service/Topic.php:14-78
Segments
Segments are used to group contacts. Unlike Topics, which focus on subscription preferences, Segments are primary grouping mechanisms for audience organization. Sources: src/Service/Segment.php:14
Segment Data Model
The Segment resource is defined by the following properties:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the segment. |
name | string | The name of the segment. |
created_at | string | Timestamp indicating when the segment was created. |
Sources: src/Segment.php:7-11
Segment Service Operations
The Resend\Service\Segment class manages segment resources.
- create(array $parameters): Creates a new segment with a provided name.
- get(string $id): Retrieves a specific segment by its ID.
- list(array $options = []): Returns a collection of segments, supporting pagination via
limit,before, andafter. - update(string $id, array $parameters): Modifies an existing segment's properties.
- remove(string $id): Deletes a segment from the system.
Sources: src/Service/Segment.php:14-80, tests/Service/Segment.php:11-73
Contact Integration
The SDK provides specialized services to manage the association between individual contacts and these organizational resources.
Contact Topics
Contacts have specific subscription states for different topics. This is managed via the Resend\Service\Contacts\Topic service. Sources: src/Service/Contacts/Topic.php:9
This diagram illustrates how an application retrieves or updates topic subscriptions for a specific contact. Sources: src/Service/Contacts/Topic.php:19-38
A contact's topic resource includes a subscription field, which can be opt_in or opt_out. Sources: src/Contacts/Topic.php:11
Contact Segments
The Resend\Service\Contacts\Segment service manages the membership of contacts within segments. Sources: src/Service/Contacts/Segment.php:9
- Add: You add a contact to a segment by calling
add($contact, $segmentId). This sends aPOSTrequest tocontacts/{contactId}/segments/{segmentId}. - List: You retrieve all segments a contact belongs to by calling
list($contactId). This sends aGETrequest tocontacts/{contactId}/segments. - Remove: You remove a contact from a segment by calling
remove($contact, $segmentId). This sends aDELETErequest tocontacts/{contactId}/segments/{segmentId}.
Sources: src/Service/Contacts/Segment.php:14-53, tests/Service/Contacts/Segment.php:10-45
Summary
Segments and Topics provide the architectural foundation for audience management in the Resend PHP SDK. Segments facilitate the grouping of contacts for organizational purposes, while Topics handle the granular subscription preferences of contacts. Through the combination of global services (Resend\Service\Segment, Resend\Service\Topic) and contact-specific services (Resend\Service\Contacts\Segment, Resend\Service\Contacts\Topic), developers can precisely control how contacts are categorized and communicated with. Sources: src/Service/Segment.php, src/Service/Topic.php, src/Service/Contacts/Segment.php, src/Service/Contacts/Topic.php