PHP SDK

The HiSend PHP SDK (hisend/hisend-php) provides a convenient wrapper around our REST APIs. It's the recommended way to integrate HiSend into your PHP backend or server-side frameworks (like Laravel or Symfony). It leverages Guzzle for robust HTTP requests and provides simple associative arrays to maintain flexibility with PHP 8+.

Installation

You can install the SDK via Composer:

composer require hisend/hisend-php

Initialization

Import the client and initialize it using the API Key generated in your project dashboard.

use Hisend\Hisend;

$client = new Hisend('YOUR_API_KEY');

// You can optionally override the base URL or Guzzle Client options
// $client = new Hisend('YOUR_API_KEY', [
//     'base_url' => 'https://api.hisend.app/v1/',
//     'guzzle' => ['timeout' => 5.0]
// ]);

Resources

The SDK is divided into resources, each handling a specific domain of the API. These are accessible via the initialized $client.

Emails (`$client->emails`)

The emails resource handles sending messages and fetching sent/received history.

`send(array $data)`

Sends a single email.

$result = $client->emails->send([
    'from' => 'noreply@yourdomain.com',
    'to' => ['user@example.com'],
    // Optional fields:
    'cc' => ['team@yourdomain.com'],
    'bcc' => ['hidden@yourdomain.com'],
    'subject' => 'Welcome to HiSend!',
    'html' => '<h1>Welcome!</h1><p>We are glad to have you.</p>',
    'text' => 'Welcome! We are glad to have you.',
]);

`sendBatch(array $data)`

Sends multiple emails in a single API request, useful for bulk messaging/newsletters.

$batch = [
    ['from' => 'sales@test.com', 'to' => ['a@test.com']],
    ['from' => 'sales@test.com', 'to' => ['b@test.com']],
];

$result = $client->emails->sendBatch($batch);

`list()`

Returns a list of all emails (inbound and outbound) belonging to your project.

$emails = $client->emails->list();
echo "You have " . count($emails) . " emails.";

`get(int $id)`

Retrieves the details of a specific email by its ID.

$email = $client->emails->get(1234);
echo $email['subject'];

Threads (`$client->threads`)

The threads resource handles email conversations, grouping inbound and outbound replies into manageable topics.

`list()`

Returns all conversation threads for your project, ordered by the latest message time.

$threads = $client->threads->list();

`getEmails(int $id)`

Returns all individual emails that belong to a specific Thread ID, in chronological order.

$emailsInThread = $client->threads->getEmails(849);
foreach ($emailsInThread as $msg) {
    echo "{$msg['from']}: {$msg['text_body']}\n";
}

Domains (`$client->domains`)

The domains resource manages the sender domains authorized for your project.

`list()`

Returns all domains registered to your project along with their verification statuses.

$domains = $client->domains->list();

`get(int $id)`

Retrieves the details and verification status of a specific domain by its ID.

$domain = $client->domains->get(101);

`add(array $data)`

Registers a new domain to your project. Note that it will remain pending until you verify its DNS records.

$domain = $client->domains->add([
    'name' => 'newsletter.example.com',
]);

`verify(int $id)`

Triggers a manual DNS check to verify if the required records (MX, TXT, CNAME) have been added to your registrar.

$result = $client->domains->verify($domain['id']);
echo "Verification status: " . $result['verification_status'];

`delete(int $id)`

Removes a domain from your project.

$client->domains->delete($domain['id']);

Routing (`$client->routing`)

The routing resource manages how inbound emails are processed, allowing for Catch-All or exact-address routing.

`list(int $domainId)`

Returns all inbound email routing rules configured for a specific domain.

$routes = $client->routing->list($domainId);

`get(int $domainId, int $id)`

Returns the details of a specific routing rule.

$route = $client->routing->get($domainId, $routeId);

`create(int $domainId, array $data)`

Creates a new routing rule on a specific domain.

$rule = $client->routing->create($domainId, [
    'type' => 'specific_address',
    'email_address' => 'support@yourdomain.com',
    'endpoint_ids' => [102, 103],
]);

`update(int $domainId, int $id, array $data)`

Updates an existing routing rule on a specific domain.

$updatedRule = $client->routing->update($domainId, $rule['id'], [
    'endpoint_ids' => [102],
]);

`delete(int $domainId, int $id)`

Deletes an existing inbound routing rule.

$client->routing->delete($domainId, $rule['id']);

Error Handling

All methods in the SDK will throw a Hisend\Exceptions\HisendException if the API request is rejected (e.g., HTTP 401 Unauthorized or HTTP 400 Bad Request). The exception contains the parsed error message from the API and the HTTP status code.

use Hisend\Exceptions\HisendException;

try {
    $result = $client->emails->send($req);
} catch (HisendException $e) {
    echo "Failed to send email: " . $e->getMessage() . " (Status: " . $e->getStatusCode() . ")\n";
}

PHP SDK

On this page