README

API client written in PHP providing access to the current version of the rapidmail API.

Installation With Composer

Preferred installation method is to use the Composer dependency manager.

composer require rapidmail/rapidmail-apiv3-client-php

Getting started

Create a new API client instance and provide your APIv3 credentials:

require_once __DIR__ . '/vendor/autoload.php';

use Rapidmail\ApiClient\Client;

$client = new Client('api_username_hash', 'api_password_hash');

After that you can access various services encapsulated within the client:

$mailingService = $client->mailings();

// Iterate all mailings 

foreach($mailingService->query() as $mailing) {
    var_dump($mailing);
}

Examples

Retrieve mailings

Get a list of your mailings with some filters applied:

// Filter for sent mailings newer than a given date 

var_dump(
    $mailingService->query([
        'created_since' => '2019-09-01 10:22:00',
        'status' => 'sent'
    ])
);

Retrieve recipient lists

$listService = $client->recipientlists();

foreach ($listService->query() as $list) {
    var_dump($list);
}

Retrieve recipients

$recipientsService = $client->recipients();

$collection = $recipientsService->query(
    [
        'recipientlist_id' => 123456789 // Recipientlist ID MUST be provided
    ]
);

foreach ($collection as $recipient) {
    var_dump($recipient);
}

Create a new recipient

$recipientsService = $client->recipients();

var_dump(
    $recipientsService->create(
        // Dataset: Represents the recipient dataset you're creating
        [
            'recipientlist_id' => 123456789, // Required
            'email' => 'john@example.net', // Required
            'firstname' => 'John',
            'lastname' => 'Doe',
            'gender' => 'male'
        ],
        // Flags: Configures system behavior, like sending activationmails
        [
            'send_activationmail' => 'yes'
        ]
    )
);

Error handling

Always keep in mind to handle errors properly and catch exceptions that might occur:

use \Rapidmail\ApiClient\Exception\ApiClientException;

try {
    $mailingService->query(['status' => 'unknown']);
} catch (ApiClientException $e) {
    // Catch API client exceptions
    echo "Exception raised: " . $e->getMessage();
}

Documentation

More information about using the API client can be found in the following subsections:

Known issues

Exceptions on 201 HTTP-Response-Code (used when a dataset was successfully created) are generated when using PHP Versions 7.4.5 and 8.1.2. If you're having issues with these versions, please try updating to a later version of PHP.
Client versions <1.1.7 do not work with guzzlehttp/guzzle 7.8+. Please upgrade to version 1.1.7 or later or downgrade your version of guzzlehttp/guzzle to 7.7.

Also refer to the API documentation for a complete list of the available endpoints and their parameters.

License

rapidmail APIv3 client is licensed under the terms of the BSD 2-clause license.

Support

Contact: www.rapidmail.de - support@rapidmail.de - +49 761 - 216 08 720

rapidmail / rapidmail-apiv3-client-php

Maintainers

Details