Segments API

Relevant source files

The following files were used as context for generating this wiki page:

• src/segments.rs
• src/contacts.rs
• src/lib.rs
• src/automations.rs
• src/usage.rs
• CHANGELOG.md

The Segments API manages contact lists and audience groupings within the Resend platform. It provides endpoints to create, retrieve, update, and delete segments, as well as functions to manage the relationship between contacts and these groupings. Segments allow users to segment their audience for targeted communications through broadcasts or automated sequences.

The SegmentsSvc structure implements these features, providing a Rust interface for the /segments REST endpoints. This service was renamed from Audiences in version 0.19.0 of the SDK to align with the Resend API terminology.

Sources: src/segments.rs:14-15, src/lib.rs:77, CHANGELOG.md:129-130

Service Architecture and Implementation

The SegmentsSvc acts as the primary interface for segment operations. It wraps an Arc<Config> to handle authentication and HTTP request building.

The diagram shows the relationship between the service and its primary data structures.
Sources: src/segments.rs:14-118

Segment Operations

The API provides traditional CRUD operations to manage the lifecycle of a segment. Each segment is identified by a unique SegmentId.

CRUD Methods

Method	HTTP Verb	Description	Path
create	POST	Creates a new segment with a provided name.	/segments
get	GET	Retrieves details of a specific segment by its ID.	/segments/{id}
update	PATCH	Modifies the name of an existing segment.	/segments/{id}
delete	DELETE	Removes a segment from the account.	/segments/{id}
list	GET	Returns a paginated list of all segments.	/segments

Sources: src/segments.rs:21-87

Data Structures

The Segment struct represents the data returned by the API.

• id: A unique SegmentId identifying the segment.
• name: The display name of the segment.
• created_at: An ISO 8601 timestamp indicating when the segment was created.

Sources: src/segments.rs:147-156

Contact Integration

Segments function primarily as containers for contacts. The SegmentsSvc provides a list_contacts method to retrieve all contacts associated with a specific segment. Conversely, the ContactsSvc provides methods to associate existing contacts with segments.

Managing Contacts within Segments

You manage the membership of contacts in segments through the following interactions:

1. Direct Retrieval: Use SegmentsSvc::list_contacts to find all members of a segment.
2. Contact Creation: You can assign a contact to multiple segments during creation using CreateContactOptions::with_segment.
3. Ad-hoc Assignment: Use ContactsSvc::add_contact_segment to add a contact to a segment after they have been created.
4. Removal: Use ContactsSvc::delete_contact_segment to remove a contact from a specific segment.

This diagram illustrates the workflow of creating a segment and associating a contact with it.
Sources: src/segments.rs:94-111, src/contacts.rs:144-180, src/contacts.rs:434-455

Automations and Segments

Segments are used as destinations or filters within the Automations system. An automation step can specifically target a segment to add members programmatically.

• AddToSegment Step: A Step::AddToSegment variant exists in the automations module, using AddToSegmentStepConfig.
• Configuration: The config requires a segment_id to define where the automation should place contacts.

Sources: src/automations.rs:188-191, src/automations.rs:271-274

Usage and Quotas

The Resend platform enforces limits on the number of segments an account can create. Usage statistics are available via the UsageSvc.

• used: The number of segments currently created in the account.
• limit: The maximum number of segments allowed by the current billing plan. If this is None, the segments are unlimited.

Sources: src/usage.rs:37, src/usage.rs:81-88

Summary

The Segments API provides the foundation for audience management in the resend-rs crate. It allows developers to organize contacts into logical groups that can be targeted by automated workflows or manual broadcasts. Through the SegmentsSvc, the SDK enables full CRUD capabilities and deep integration with the Contacts and Automations modules to facilitate complex email marketing strategies.

Sources: src/segments.rs:1-120, src/contacts.rs:144-180