Contact Imports

Relevant source files

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

• src/Service/Contacts/Import.php
• src/Contacts/Import.php
• tests/Fixtures/Contacts/Import.php
• tests/Service/Contacts/Import.php
• src/Service/Contact.php
• tests/ValueObjects/Transporter/Payload.php

The Contact Imports module manages the bulk ingestion of contact data into the Resend platform. It provides specialized services to upload files, monitor the progress of import jobs, and retrieve statistics regarding the success or failure of processed records.

This module is integrated as a sub-service within the broader Contact service, allowing developers to initiate asynchronous import tasks rather than creating contacts individually.

Sources: src/Service/Contact.php:11-28, src/Service/Contacts/Import.php:9-11

Architecture and Class Structure

The module follows the standard Resend SDK pattern, separating the service logic (API interaction) from the resource representation (data objects).

• Resend\Service\Contacts\Import: This class contains the methods required to interact with the /contacts/imports API endpoints. It handles the preparation of payloads and transportation of data.
• Resend\Contacts\Import: A data transfer object that represents a single import job, containing metadata such as status, timestamps, and processing counts.

Sources: src/Service/Contacts/Import.php:9-11, src/Contacts/Import.php:16-19

Relationship Diagram

The following class diagram shows how the Import service is nested within the Contact service.

Data Model

The Import resource encapsulates all details of a bulk import operation. It includes a specific counts object that provides granular visibility into the processing results.

Import Resource Fields

Property	Type	Description
id	string	Unique identifier for the contact import job.
status	string	Current state (e.g., completed, processing).
created_at	string	Timestamp when the import was initiated.
completed_at	string|null	Timestamp when the import finished processing.
counts	array	Breakdown of record processing results.

Sources: src/Contacts/Import.php:8-14, tests/Fixtures/Contacts/Import.php:5-15

Processing Counts Breakdown

The counts array tracks the lifecycle of each row in the imported file:

• total: The total number of records detected in the file.
• created: Records successfully added as new contacts.
• updated: Existing contacts that were modified by the import.
• skipped: Records ignored due to duplication or configuration.
• failed: Records that encountered errors during ingestion.

Sources: tests/Fixtures/Contacts/Import.php:10-16

Core Operations

Creating an Import

Imports are initiated by sending a file resource (typically a CSV) along with optional configuration parameters like a column_map. The service utilizes a multipart/form-data request for these uploads.

Managing Imports

You can retrieve the status of a specific import or list all historical imports.

• Retrieve: The get(string $id) method fetches the current status and counts for a specific job.
• List: The list(array $options) method returns a collection of import resources, supporting filters for status and pagination using limit, before, and after.

Sources: src/Service/Contacts/Import.php:17-48

Technical Implementation Details

Multipart Upload Handling

The Payload::upload helper manages the complexities of file transmission. When creating an import, the SDK performs the following:

1. Sets the Content-Type header to multipart/form-data.
2. Generates a unique boundary for the request body.
3. Encodes scalar fields (like names) and arrays (like column_map) as standard form parts.
4. Attaches the file stream as a binary part with a Content-Disposition naming the field as file.

Sources: tests/ValueObjects/Transporter/Payload.php:143-200

Usage Example

The following snippet demonstrates how to initiate an import using a file stream.

$file = fopen('contacts.csv', 'r');

$result = $resend->contacts->imports->create([
    'file' => $file,
]);

// Accessing the ID for status tracking
$importId = $result->id;

Sources: tests/Service/Contacts/Import.php:20-31

Summary

Contact Imports provide a robust mechanism for bulk data management. By leveraging multipart uploads and providing detailed processing counts, the system allows developers to scale contact lists efficiently while maintaining visibility into the integrity of the imported data.