Relevant source files

The following files were used as context for generating this wiki page: - [src/Segment.php](https://github.com/resend/resend-php/blob/main/src/Segment.php) - [src/Service/Segment.php](https://github.com/resend/resend-php/blob/main/src/Service/Segment.php) - [src/Service/Contacts/Segment.php](https://github.com/resend/resend-php/blob/main/src/Service/Contacts/Segment.php) - [src/Service/Contact.php](https://github.com/resend/resend-php/blob/main/src/Service/Contact.php) - [tests/Fixtures/Segment.php](https://github.com/resend/resend-php/blob/main/tests/Fixtures/Segment.php) - [tests/Service/Segment.php](https://github.com/resend/resend-php/blob/main/tests/Service/Segment.php) - [tests/Service/Contacts/Segment.php](https://github.com/resend/resend-php/blob/main/tests/Service/Contacts/Segment.php)

# Segments Segments provide a mechanism to group and categorize contacts within the Resend ecosystem. This system allows for the programmatic creation, retrieval, listing, and deletion of segments, as well as the ability to associate or dissociate specific contacts with these groupings for targeted communication. The Segments module is partitioned into two primary functional areas: global segment management (CRUD operations on segments themselves) and contact-specific segment management (managing which segments a particular contact belongs to). ## Architecture and Data Models ### Segment Resource The core data structure is the `Segment` class, which extends the base `Resource` class. It acts as a Data Transfer Object (DTO) representing the state of a segment as returned by the Resend API. | Field | Type | Description | | :--- | :--- | :--- | | `id` | string | The unique identifier for the segment (UUID). | | `name` | string | The display name of the segment. | | `created_at` | string | ISO 8601 timestamp of when the segment was created. | Sources: [src/Segment.php:7-13](), [tests/Fixtures/Segment.php:3-10]() ### Service Structure The functionality is distributed across two specialized service classes: 1. **`Resend\Service\Segment`**: Handles top-level segment operations. 2. **`Resend\Service\Contacts\Segment`**: Handles the relationship between a specific contact and segments. This service is initialized within the main `Contact` service. ```mermaid classDiagram class Resource { <> } class Segment { +string id +string name +string created_at } class Service { <> #Transporter transporter } class GlobalSegmentService { +get(string id) +create(array params) +list(array options) +remove(string id) } class ContactSegmentService { +add(string contact, string segmentId) +list(string contactId, array options) +remove(string contact, string segmentId) } Resource <|-- Segment Service <|-- GlobalSegmentService Service <|-- ContactSegmentService ContactSegmentService --* ContactService : initialized in ``` The diagram shows the relationship between the Segment resource and the services that manage them. Sources: [src/Segment.php:14](), [src/Service/Segment.php:9](), [src/Service/Contacts/Segment.php:9](), [src/Service/Contact.php:17-26]() ## Segment Management Global segment management is handled via the `segments` property on the Resend client. It supports standard CRUD operations through the `Resend\Service\Segment` class. ### CRUD Operations * **Create**: Generates a new segment by providing a name. * **Get**: Retrieves a single segment's details using its unique ID. * **List**: Returns a `Collection` of all existing segments. * **Remove**: Deletes a segment from the system. ```mermaid sequenceDiagram participant User participant Service as GlobalSegmentService participant Transporter participant API as Resend_API User->>Service: create(['name' => 'Registered Users']) Service->>Transporter: request(Payload::create('segments', ...)) Transporter->>API: POST /segments API-->>Transporter: {id: "uuid", name: "Registered Users", ...} Transporter-->>Service: raw_array Service-->>User: Segment Resource Object ``` The sequence shows the typical flow for creating a segment resource. Sources: [src/Service/Segment.php:14-65](), [tests/Service/Segment.php:9-47]() ## Contact-Segment Associations Management of contact membership within segments is performed via the `Resend\Service\Contacts\Segment` service. This is accessed through the contact service: `$resend->contacts->segments`. ### Operations Workflow | Method | Description | Path Parameter Pattern | | :--- | :--- | :--- | | `add` | Associates a contact with a segment. | `contacts/{contactId}/segments/{segmentId}` | | `list` | Lists all segments associated with a specific contact. | `contacts/{contactId}/segments` | | `remove` | Removes a contact from a specific segment. | `contacts/{contactId}/segments/{segmentId}` | Sources: [src/Service/Contacts/Segment.php:11-38](), [tests/Service/Contacts/Segment.php:9-44]() ### Membership Data Flow When adding a contact to a segment, the SDK constructs a request targeted at the specific contact's sub-resource path. ```mermaid flowchart TD Start[Add Contact to Segment] --> Payload[Create Payload] Payload --> Path{Path Construction} Path --> PathValue[contacts/CONTACT_ID/segments/SEGMENT_ID] PathValue --> Request[Transporter Request] Request --> Result[Create Segment Resource] Result --> End[Return Segment] ``` The flow details how the SDK routes contact-specific segment requests. Sources: [src/Service/Contacts/Segment.php:11-18]() ## Implementation Details ### Payload Generation The services utilize a `Payload` value object to standardize API requests. For example, listing segments supports pagination options like `limit`, `before`, and `after`. ```php // Example of listing segments with options $payload = Payload::list('segments', [ 'limit' => 20, 'after' => 'cursor_id' ]); ``` Sources: [src/Service/Segment.php:48](), [src/Service/Contacts/Segment.php:30]() ### Service Initialization The `Contact` service explicitly instantiates the contact-specific segment service during its own construction, ensuring the nested API structure (`$resend->contacts->segments`) is available. ```php namespace Resend\Service; class Contact extends Service { public Segment $segments; public function __construct(Transporter $transporter) { $this->segments = new \Resend\Service\Contacts\Segment($transporter); parent::__construct($transporter); } } ``` Sources: [src/Service/Contact.php:13-26]() ## Summary The Segments module in the Resend PHP SDK provides a comprehensive interface for audience management. By separating global segment definitions from contact-level associations, the architecture maintains a clear distinction between the grouping entities and the membership logic required for targeted email delivery.