### Install Maileon API Client via Composer

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Command to add the library to a PHP project.

```bash
composer require xqueue/maileon-api-client
```

--------------------------------

### Get Detailed Opens and Clicks with Maileon API

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Retrieves detailed open and click events, including contact information, device data, and link details. Ensure the API key is correctly configured.

```php
<?php
use de\xqueue\maileon\api\client\reports\ReportsService;
use de\xqueue\maileon\api\client\contacts\StandardContactField;

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

$reportsService = new ReportsService([
    'API_KEY' => 'your-api-key-here',
]);

// Get opens with contact details and email client info
$opens = $reportsService->getOpens(
    mailingIds: [12345],
    standardFields: [StandardContactField::$FIRSTNAME, StandardContactField::$LASTNAME],
    embedEmailClientInfos: true,
    deviceTypeFilter: [' MOBILE', 'TABLET'],
    pageIndex: 1,
    pageSize: 100
);

foreach ($opens->getResult() as $open) {
    echo "Opened by: " . $open->contact->email . "\n";
    echo "Device: " . $open->deviceType . "\n";
    echo "Timestamp: " . $open->timestamp . "\n";
}

// Get clicks with link details
$clicks = $reportsService->getClicks(
    mailingIds: [12345],
    embedLinkTags: true,
    embedEmailClientInfos: true,
    pageIndex: 1,
    pageSize: 100
);

foreach ($clicks->getResult() as $click) {
    echo "Clicked by: " . $click->contact->email . "\n";
    echo "Link URL: " . $click->linkUrl . "\n";
    echo "Link ID: " . $click->linkId . "\n";
}

```

--------------------------------

### Get Contact by Email - PHP

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Retrieves contact data, including standard and custom fields, by email address. Requires API key and specific service imports. Handles success and error responses.

```php
<?php
use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\StandardContactField;

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

$contactsService = new ContactsService([
    'API_KEY' => 'your-api-key-here',
]);

$result = $contactsService->getContactByEmail(
    email: 'john.doe@example.com',
    standard_fields: [
        StandardContactField::$FIRSTNAME,
        StandardContactField::$LASTNAME,
        StandardContactField::$CITY,
    ],
    custom_fields: ['customer_id', 'signup_source']
);

if ($result->isSuccess()) {
    $contact = $result->getResult();
    echo "ID: " . $contact->id . "\n";
    echo "Email: " . $contact->email . "\n";
    echo "Permission: " . $contact->permission->getType() . "\n";
    echo "First Name: " . $contact->standard_fields[StandardContactField::$FIRSTNAME] . "\n";
    echo "Customer ID: " . $contact->custom_fields['customer_id'] . "\n";
}

```

--------------------------------

### Get Bounce Information with Maileon API

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Retrieves bounce information, allowing filtering by type (permanent/transient) and status codes. Also fetches the count of unique bounces. Ensure the API key is correctly configured.

```php
<?php
use de\xqueue\maileon\api\client\reports\ReportsService;

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

$reportsService = new ReportsService([
    'API_KEY' => 'your-api-key-here',
]);

// Get permanent bounces (hard bounces)
$permanentBounces = $reportsService->getBounces(
    mailingIds: [12345],
    typeFilter: 'permanent',
    pageIndex: 1,
    pageSize: 100
);

foreach ($permanentBounces->getResult() as $bounce) {
    echo "Bounced: " . $bounce->contact->email . "\n";
    echo "Status Code: " . $bounce->statusCode . "\n";
    echo "Type: " . $bounce->type . "\n";
}

// Get unique bounces count
$uniqueBounceCount = $reportsService->getUniqueBouncesCount(
    mailingIds: [12345],
    excludeAnonymousBounces: true
)->getResult();

echo "Unique bounces: $uniqueBounceCount\n";

```

--------------------------------

### Create and Send Mailing with MailingsService

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Demonstrates how to initialize the service, configure mailing metadata, set HTML and text content, and trigger immediate dispatch.

```php
<?php
use de\xqueue\maileon\api\client\mailings\MailingsService;

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

$mailingsService = new MailingsService([
    'API_KEY' => 'your-api-key-here',
]);

// Create a new mailing
$result = $mailingsService->createMailing(
    name: 'Summer Sale Newsletter',
    subject: 'Hi [CONTACT|FIRSTNAME]! Our Summer Sale starts now!',
    type: 'regular'
);

$mailingId = $result->getResult();

// Configure the mailing
$mailingsService->setSender($mailingId, 'newsletter@yourcompany.com');
$mailingsService->setSenderAlias($mailingId, 'YourCompany Newsletter');
$mailingsService->setPreviewText($mailingId, 'Save up to 50% on summer items');

// Set HTML content with image grabbing and link tracking
$htmlContent = '
<html>
<body>
    <h1>Summer Sale!</h1>
    <p>Dear [CONTACT|FIRSTNAME],</p>
    <p>Don\'t miss our exclusive summer deals!</p>
    <a href="https://yourshop.com/sale">Shop Now</a>
</body>
</html>';

$mailingsService->setHTMLContent(
    mailingId: $mailingId,
    html: $htmlContent,
    doImageGrabbing: true,
    doLinkTracking: true
);

// Set text version for non-HTML clients
$mailingsService->setTextContent($mailingId, 'Summer Sale! Visit https://yourshop.com/sale');

// Assign target group
$mailingsService->setTargetGroupId($mailingId, 123);

// Send immediately
$mailingsService->sendMailingNow($mailingId);

echo "Mailing $mailingId sent!\n";
```

--------------------------------

### Create and Send a Mailing

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Demonstrates the workflow of creating a mailing, configuring sender details, setting HTML content, attaching a target group, and triggering an immediate send.

```php
<?php

use de\xqueue\maileon\api\client\mailings\MailingsService;

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

$mailingsService = new MailingsService([
    'API_KEY' => 'Your API key',
]);

$mailingId = $mailingsService->createMailing(
    name:'My campaign name',
    subject:'Hi [CONTACT|FIRSTNAME]! We got some news for you!'
)->getResult();

$mailingsService->setSender($mailingId, 'foo@bar.com');
$mailingsService->setSenderAlias($mailingId, 'Maileon news team');
$mailingsService->setHTMLContent(
    mailingId:$mailingId,
    html:'<html>...</html>',
    doImageGrabbing:true,
    doLinkTracking:true
);
$mailingsService->setTargetGroupId($mailingId, 123);
$mailingsService->sendMailingNow($mailingId);
```

--------------------------------

### Configure Maileon API Client Options

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Initialize services with various configuration options including API key, base URI, debug mode, exception handling, timeouts, and proxy settings. Debugging can also be toggled at runtime.

```php
<?php
use de
amespace	olacklistslacklistsService;

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

$service = new ContactsService([
    // Required: Your Maileon API key
    'API_KEY' => 'your-api-key-here',

    // Optional: Custom base URI (default: https://api.maileon.com/1.0)
    'BASE_URI' => 'https://api.maileon.com/1.0',

    // Optional: Enable debug output (default: false)
    'DEBUG' => true,

    // Optional: Throw exceptions on errors (default: true)
    'THROW_EXCEPTION' => true,

    // Optional: Request timeout in seconds (default: 5)
    'TIMEOUT' => 30,

    // Optional: Proxy configuration
    'PROXY_HOST' => '192.168.1.100',
    'PROXY_PORT' => 8080,
]);

// Enable/disable debugging at runtime
$service->setDebug(true);
echo "Debug mode: " . ($service->isDebug() ? 'enabled' : 'disabled') . "\n";
```

--------------------------------

### Schedule Mailing with MailingsService

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Shows how to set specific delivery times and configure distribution options for future mailing dispatch.

```php
<?php
use de\xqueue\maileon\api\client\mailings\MailingsService;

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

$mailingsService = new MailingsService([
    'API_KEY' => 'your-api-key-here',
]);

$mailingId = 12345;

// Schedule for a specific date and time
$mailingsService->setMailingSchedule(
    mailingId: $mailingId,
    date: '2024-12-25',
    hours: '10',
    minutes: '00'
);

// Schedule with uniform distribution over 24 hours
$mailingsService->setMailingSchedule(
    mailingId: $mailingId,
    date: '2024-12-25',
    hours: '08',
    minutes: '00',
    dispatchOption: 'uniform',
    dispatchEndInHours: 24,
    dispatchUniformInterval: 'hour'
);

// Get current schedule
$schedule = $mailingsService->getMailingSchedule($mailingId);
print_r($schedule->getResult());

// Delete schedule if needed
$mailingsService->deleteMailingSchedule($mailingId);
```

--------------------------------

### Retrieve Mailing KPIs with ReportsService

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Fetches various performance metrics for a mailing, such as opens, clicks, and bounces. Includes logic for calculating open and click-to-open rates.

```php
<?php
use de
xqueue
maileon
api
client
reports
ReportsService;

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

$reportsService = new ReportsService([
    'API_KEY' => 'your-api-key-here',
]);

$mailingId = 12345;

// Get KPI counts for a specific mailing
$recipients = $reportsService->getRecipientsCount(mailingIds: [$mailingId])->getResult();
$opens = $reportsService->getOpensCount(mailingIds: [$mailingId])->getResult();
$uniqueOpens = $reportsService->getUniqueOpensCount(mailingIds: [$mailingId])->getResult();
$clicks = $reportsService->getClicksCount(mailingIds: [$mailingId])->getResult();
$uniqueClicks = $reportsService->getUniqueClicksCount(mailingIds: [$mailingId])->getResult();
$bounces = $reportsService->getBouncesCount(mailingIds: [$mailingId])->getResult();
$unsubscribes = $reportsService->getUnsubscribersCount(mailingIds: [$mailingId])->getResult();
$conversions = $reportsService->getConversionsCount(mailingIds: [$mailingId])->getResult();

echo "Mailing Performance Report\n";
echo "Recipients: $recipients\n";
echo "Opens: $opens (Unique: $uniqueOpens)\n";
echo "Clicks: $clicks (Unique: $uniqueClicks)\n";
echo "Bounces: $bounces\n";
echo "Unsubscribes: $unsubscribes\n";
echo "Conversions: $conversions\n";

// Calculate rates
$openRate = $recipients > 0 ? ($uniqueOpens / $recipients) * 100 : 0;
$clickRate = $uniqueOpens > 0 ? ($uniqueClicks / $uniqueOpens) * 100 : 0;
echo "Open Rate: " . number_format($openRate, 2) . "%\n";
echo "Click-to-Open Rate: " . number_format($clickRate, 2) . "%\n";

// Get mailing summary (all KPIs at once)
$summaries = $reportsService->getMailingSummaries([$mailingId]);
```

--------------------------------

### Create a new contact

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Creates a contact with standard and custom fields, including optional DOI (Double Opt-In) settings.

```php
<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\Contact;
use de\xqueue\maileon\api\client\contacts\Permission;
use de\xqueue\maileon\api\client\contacts\Preference;
use de\xqueue\maileon\api\client\contacts\StandardContactField;
use de\xqueue\maileon\api\client\contacts\SynchronizationMode;

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

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
]);

$contact = new Contact(
    email:'foo@bar.com',
    standard_fields:[
        StandardContactField::$FIRSTNAME => 'Foo',
        StandardContactField::$LASTNAME => 'Bar',
    ],
    custom_fields:[
        'My custom field in Maileon' => 'A value corresponding to the field type',
    ],
);

$creation = $contactsService->createContact(
    contact:$contact,
    syncMode:SynchronizationMode::$IGNORE,
    src:'An optional source of the contact creation',
    subscriptionPage:'An additional source of the contact creation',
    doi:true,
    doiPlus:true, // Enable single user tracking with the DOI process
    doiMailingKey:'A key to identify the DOI mailing',
);

if (!$creation->isSuccess()) {
    die($creation->getResultXML()->message);
}
```

--------------------------------

### Configure Maileon Webhooks

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Utilize WebhooksService to create, retrieve, update, and delete webhooks for real-time event notifications. Ensure the webhook URL is accessible.

```php
<?php
use de
amespace	olacklistslacklistsService;
use de
amespace	olacklistslacklistslacklists;

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

$webhooksService = new WebhooksService([
    'API_KEY' => 'your-api-key-here',
]);

// Get all webhooks
$result = $webhooksService->getWebhooks();
if ($result->isSuccess() && $result->getResult()) {
    foreach ($result->getResult() as $webhook) {
        echo "Webhook: " . $webhook->url . " (ID: " . $webhook->id . ")\n";
    }
}

// Create new webhook
$webhook = new Webhook();
$webhook->url = 'https://yourapp.com/maileon-webhook';
$webhook->event = 'unsubscription';
$webhook->active = true;

$webhooksService->createWebhook($webhook);

// Get specific webhook
$webhook = $webhooksService->getWebhook(123);

// Update webhook
$webhook->active = false;
$webhooksService->updateWebhook(123, $webhook);

// Delete webhook
$webhooksService->deleteWebhook(123);
```

--------------------------------

### Retrieve basic contact data by email

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Fetches contact information using an email address. Requires an initialized ContactsService with a valid API key.

```php
<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;

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

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
]);

$contact = $contactsService->getContactByEmail('foo@bar.com')->getResult();

/**
* The contact object stores all information you requested.
* 
* Identifiers (Maileon ID, Maileon external id and email address), marketing permission
* level, creation date and last update date are always included if they are set in Maileon.
* 
* ID: $contact->id
* Email: $contact->email
* Permission: $contact->permission->getType()
*/
```

--------------------------------

### Fetch KPI Data for a Mailing

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Retrieves various performance metrics including recipients, opens, clicks, unsubscribes, and conversions for a specific mailing ID.

```php
<?php

use de\xqueue\maileon\api\client\reports\ReportsService;

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

$reportsService = new ReportsService([
    'API_KEY' => 'Your API key',
]);

$mailingId = 123;

$recipients = $reportsService->getRecipientsCount(mailingIds:[$mailingId])->getResult();
$opens = $reportsService->getOpensCount(mailingIds:[$mailingId])->getResult();
$clicks = $reportsService->getClicksCount(mailingIds:[$mailingId])->getResult();
$unsubscribers = $reportsService->getUnsubscribersCount(mailingIds:[$mailingId])->getResult();
$conversions = $reportsService->getConversionsCount(mailingIds:[$mailingId])->getResult();
```

--------------------------------

### Manage Mailing Attachments

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Provides methods to attach files from local paths or binary data and retrieve attachment information.

```php
<?php
use de\xqueue\maileon\api\client\mailings\MailingsService;

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

$mailingsService = new MailingsService([
    'API_KEY' => 'your-api-key-here',
]);

$mailingId = 12345;

// Add attachment from file
$mailingsService->addAttachmentFromFile(
    mailingId: $mailingId,
    filename: '/path/to/document.pdf',
    contentType: 'application/pdf',
    attachmentFileName: 'Summer-Catalog.pdf'
);

// Add attachment from binary content
$pdfContent = file_get_contents('/path/to/invoice.pdf');
$mailingsService->addAttachment(
    mailingId: $mailingId,
    filename: 'Invoice.pdf',
    contentType: 'application/pdf',
    contents: $pdfContent
);

// List all attachments
$attachments = $mailingsService->getAttachments($mailingId);
foreach ($attachments->getResult() as $attachment) {
    echo "Attachment: " . $attachment->filename . "\n";
}

// Get attachment count
$count = $mailingsService->getAttachmentsCount($mailingId)->getResult();
echo "Total attachments: $count\n";
```

--------------------------------

### Manage Maileon Blacklists

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Use BlacklistsService to retrieve, add, and manage email blacklists. Ensure the API key is correctly configured.

```php
<?php
use de
amespace	olacklistslacklistsService;

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

$blacklistsService = new BlacklistsService([
    'API_KEY' => 'your-api-key-here',
]);

// Get all blacklists
$blacklists = $blacklistsService->getBlacklists();
foreach ($blacklists->getResult() as $blacklist) {
    echo "Blacklist: " . $blacklist->name . " (ID: " . $blacklist->id . ")\n";
}

// Get blacklist with entries
$blacklist = $blacklistsService->getBlacklist(123);
foreach ($blacklist->getResult()->entries as $entry) {
    echo "Entry: $entry\n";
}

// Add entries to blacklist
$blacklistsService->addEntriesToBlacklist(
    id: 123,
    entries: [
        'spam@example.com',
        'bounce@example.com',
        '*@competitor.com'  // Wildcard for entire domain
    ],
    importName: 'Manual Import 2024-01'
);
```

--------------------------------

### Paginate Through Unsubscribers with Maileon API

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Iterates through all unsubscribers using pagination, fetching data in chunks. Also retrieves a summary of unsubscription reasons. Ensure the API key is correctly configured.

```php
<?php
use de\xqueue\maileon\api\client\reports\ReportsService;

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

$reportsService = new ReportsService([
    'API_KEY' => 'your-api-key-here',
]);

$pageIndex = 1;
$pageSize = 1000;

do {
    $result = $reportsService->getUnsubscribers(
        fromDate: strtotime('-30 days') * 1000,
        pageIndex: $pageIndex,
        pageSize: $pageSize
    );

    foreach ($result->getResult() as $unsubscriber) {
        echo sprintf(
            "%s unsubscribed from mailing %d at %s\n",
            $unsubscriber->contact->email,
            $unsubscriber->mailingId,
            $unsubscriber->timestamp
        );
    }

    $totalPages = (int) $result->getResponseHeader('x-pages');
    $pageIndex++;

} while ($pageIndex <= $totalPages);

// Get unsubscription reasons summary
$reasons = $reportsService->getUnsubscriberReasons(
    fromDate: strtotime('-30 days') * 1000,
    order: 'count',
    asc: false
);

foreach ($reasons->getResult() as $reason) {
    echo "Reason: " . $reason->name . " (Count: " . $reason->count . ")\n";
}

```

--------------------------------

### Synchronize contacts in bulk

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Performs bulk synchronization of a large list of contacts. Useful for batch processing and data migration.

```php
<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\Contacts;
use de\xqueue\maileon\api\client\contacts\Contact;
use de\xqueue\maileon\api\client\contacts\Permission;
use de\xqueue\maileon\api\client\contacts\SynchronizationMode;
use de\xqueue\maileon\api\client\contacts\StandardContactField;

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

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
]);

$contactList = new Contacts();

for ($i=1; $i<=10000; $i++) {
    $contactList->addContact(
        new Contact(
            email:"foo-{$i}@bar.com",
            standard_fields:[
                StandardContactField::$FIRSTNAME => 'Foo',
                StandardContactField::$LASTNAME => 'Bar',
            ],
            custom_fields:[
                'My custom field in Maileon' => 'A value corresponding to the field type',
            ],
        )
    );
}

$response = $contactsService->synchronizeContacts(
    contacts:$contactList,
    syncMode:SynchronizationMode::$IGNORE,
    useExternalId:false,
    ignoreInvalidContacts:true,
    reimportUnsubscribedContacts:false,
    overridePermission:false,
    updateOnly:false,
);

// The response contains some statistics and, if ignore_invalid_contacts is set
// to true, information about possibly failed contact creations, see
// https://maileon.com/support/synchronize-contacts/#articleTOC_3
```

--------------------------------

### Filter Mailings by Criteria

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Demonstrates retrieving lists of mailings based on state, type, keywords, or scheduling time.

```php
<?php
use de\xqueue\maileon\api\client\mailings\MailingsService;

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

$mailingsService = new MailingsService([
    'API_KEY' => 'your-api-key-here',
]);

// Get mailings by state
$draftMailings = $mailingsService->getMailingsByStates(
    states: ['draft', 'scheduled'],
    fields: ['name', 'subject', 'created'],
    page_index: 1,
    page_size: 50
);

// Get mailings by type
$triggerMailings = $mailingsService->getMailingsByTypes(
    types: ['trigger', 'doi'],
    fields: ['name', 'state'],
    page_index: 1,
    page_size: 100
);

// Get mailings by keywords/tags
$campaignMailings = $mailingsService->getMailingsByKeywords(
    keywords: ['summer', 'sale'],
    keywordsOp: 'and',
    fields: ['name', 'subject']
);

// Get mailings scheduled before a date
$scheduledMailings = $mailingsService->getMailingsBySchedulingTime(
    scheduleTime: '2024-12-31 23:59:59',
    beforeSchedulingTime: true,
    fields: ['name', 'schedule']
);
```

--------------------------------

### Manage Custom Fields using PHP

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

This snippet demonstrates how to create, retrieve, rename, and delete custom fields for contacts using the Maileon PHP API client. Ensure the API client and necessary classes are autoloaded.

```php
<?php
use de\xqueue\maileon\api\client\contacts\ContactsService;

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

$contactsService = new ContactsService([
    'API_KEY' => 'your-api-key-here',
]);

// Create a new custom field
$contactsService->createCustomField('loyalty_points', 'integer');
$contactsService->createCustomField('preferred_category', 'string');
$contactsService->createCustomField('last_purchase_date', 'date');
$contactsService->createCustomField('newsletter_subscriber', 'boolean');

// Get all custom fields
$result = $contactsService->getCustomFields();
if ($result->isSuccess()) {
    foreach ($result->getResult() as $field) {
        echo "Field: " . $field->name . " (Type: " . $field->type . ")\n";
    }
}

// Rename a custom field
$contactsService->renameCustomField('preferred_category', 'favorite_category');

// Delete a custom field (also deletes all values)
$contactsService->deleteCustomField('loyalty_points');

```

--------------------------------

### Configure SSL for CURL in php.ini

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Required for enabling SSL support in CURL to connect to the API endpoint.

```ini
curl.cainfo="your-path-to-the-bundle/cacert.pem"
```

--------------------------------

### Retrieve Unsubscriptions via ReportsService

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Iterates through paginated unsubscription data for a mailing list.

```php
<?php

use de\xqueue\maileon\api\client\reports\ReportsService;

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

$contactsService = new ReportsService([
    'API_KEY' => 'Your API key',
]);

$index = 1;
do {
    $getUnsubscribers = $contactsService->getUnsubscribers(
        pageIndex:$index++,
        pageSize:1000
    );
    
    foreach ($getUnsubscribers->getResult() as $unsubscriber) {
        printf('%s unsubscribed in mailing %u at %s'.PHP_EOL,
            $unsubscriber->contact->email,
            $unsubscriber->mailingId,
            $unsubscriber->timestamp
        );
    }
} while($getUnsubscribers->getResponseHeader('x-pages') >= $index);
```

--------------------------------

### Synchronize Contacts in Bulk using PHP

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Use this method to synchronize a large number of contacts with your Maileon account. It supports detailed error reporting for validation issues. Ensure the API client and necessary classes are autoloaded.

```php
<?php
use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\Contacts;
use de\xqueue\maileon\api\client\contacts\Contact;
use de\xqueue\maileon\api\client\contacts\Permission;
use de\xqueue\maileon\api\client\contacts\SynchronizationMode;
use de\xqueue\maileon\api\client\contacts\StandardContactField;

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

$contactsService = new ContactsService([
    'API_KEY' => 'your-api-key-here',
]);

$contactList = new Contacts();

// Add contacts from your data source
$subscribers = [
    ['email' => 'user1@example.com', 'firstname' => 'Alice', 'lastname' => 'Smith'],
    ['email' => 'user2@example.com', 'firstname' => 'Bob', 'lastname' => 'Jones'],
    ['email' => 'user3@example.com', 'firstname' => 'Carol', 'lastname' => 'Williams'],
];

foreach ($subscribers as $subscriber) {
    $contactList->addContact(
        new Contact(
            email: $subscriber['email'],
            standard_fields: [
                StandardContactField::$FIRSTNAME => $subscriber['firstname'],
                StandardContactField::$LASTNAME => $subscriber['lastname'],
            ]
        )
    );
}

$response = $contactsService->synchronizeContacts(
    contacts: $contactList,
    permission: Permission::$SOI,
    syncMode: SynchronizationMode::$UPDATE,
    useExternalId: false,
    ignoreInvalidContacts: true,
    reimportUnsubscribedContacts: false,
    overridePermission: false,
    updateOnly: false
);

// Response contains synchronization statistics and any validation errors
echo "Synchronization complete\n";

```

--------------------------------

### Create or Update Contact with DOI - PHP

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Creates a new contact or updates an existing one. Optionally triggers a double opt-in (DOI) process for GDPR compliance. Requires API key and specific service imports.

```php
<?php
use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\Contact;
use de\xqueue\maileon\api\client\contacts\Permission;
use de\xqueue\maileon\api\client\contacts\StandardContactField;
use de\xqueue\maileon\api\client\contacts\SynchronizationMode;

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

$contactsService = new ContactsService([
    'API_KEY' => 'your-api-key-here',
]);

$contact = new Contact(
    email: 'john.doe@example.com',
    standard_fields: [
        StandardContactField::$FIRSTNAME => 'John',
        StandardContactField::$LASTNAME => 'Doe',
        StandardContactField::$CITY => 'Berlin',
    ],
    custom_fields: [
        'customer_id' => '12345',
        'signup_source' => 'website',
    ],
);

$result = $contactsService->createContact(
    contact: $contact,
    syncMode: SynchronizationMode::$UPDATE,
    src: 'Website Registration',
    subscriptionPage: 'homepage-newsletter',
    doi: true,
    doiPlus: true,
    doiMailingKey: 'welcome_doi_mailing'
);

if ($result->isSuccess()) {
    echo "Contact created successfully\n";
} else {
    echo "Error: " . $result->getResultXML()->message . "\n";
}

```

--------------------------------

### Send Transactional Email with TransactionsService

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Sends a transactional email by defining a Transaction object with contact details and dynamic content. Requires an API key for service initialization.

```php
<?php
use de
xqueue
maileon
api
client
transactions
TransactionsService;
use de
xqueue
maileon
api
client
transactions
Transaction;
use de
xqueue
maileon
api
client
transactions
ContactReference;

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

$transactionsService = new TransactionsService([
    'API_KEY' => 'your-api-key-here',
]);

// Send order confirmation with product details
$transaction = new Transaction(
    typeName: 'order_confirmation',
    contact: new ContactReference(
        email: 'customer@example.com'
    ),
    content: [
        'order_id' => 'ORD-2024-12345',
        'order_date' => '2024-01-15',
        'total_amount' => 149.99,
        'currency' => 'EUR',
        'shipping_address' => [
            'name' => 'John Doe',
            'street' => '123 Main St',
            'city' => 'Berlin',
            'zip' => '10115'
        ],
        'items' => [
            [
                'name' => 'Premium Widget',
                'sku' => 'WDG-001',
                'quantity' => 2,
                'price' => 49.99,
                'image_url' => 'https://shop.com/images/widget.jpg'
            ],
            [
                'name' => 'Deluxe Gadget',
                'sku' => 'GDG-002',
                'quantity' => 1,
                'price' => 50.01,
                'image_url' => 'https://shop.com/images/gadget.jpg'
            ]
        ]
    ]
);

$result = $transactionsService->createTransactions(
    transactions: [$transaction],
    ignoreInvalidEvents: true,
    generateTransactionId: true
);

if ($result->isSuccess()) {
    $report = $result->getResult();
    echo "Transaction sent successfully\n";
}
```

--------------------------------

### Send Transactional Data

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Creates and sends a transaction event, such as an order confirmation, including custom content and product item details.

```php
<?php

use de\xqueue\maileon\api\client\transactions\ContactReference;
use de\xqueue\maileon\api\client\transactions\Transaction;
use de\xqueue\maileon\api\client\transactions\TransactionsService;

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

$transactionsService = new TransactionsService([
    'API_KEY' => 'Your API key',
]);

$transaction = new Transaction(
    typeName:'My event to trigger',
    contact:new ContactReference(
        email:'foo@bar.com'
    ),
    content:[
        'foo' => 'bar',
        'items' => [
            [
                'name' => 'foo',
                'quantity' => 2,
                'price' => 27.99
            ],
            [
                'name' => 'bar',
                'quantity' => 1,
                'price' => 16.49
            ],
        ],
    ]
);

$transactionsService->createTransactions([$transaction]);
```

--------------------------------

### Retrieve contact with specific fields and validation

Source: https://github.com/xqueue/maileon-php-api-client/blob/master/README.md

Fetches a contact while requesting specific standard and custom fields. Includes a check for successful API response.

```php
<?php

use de\xqueue\maileon\api\client\contacts\ContactsService;
use de\xqueue\maileon\api\client\contacts\StandardContactField;

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

$contactsService = new ContactsService([
    'API_KEY' => 'Your API key',
]);

$getContact = $contactsService->getContactByEmail(
    email:'foo@bar.com',
    standard_fields:[
        StandardContactField::$FIRSTNAME,
        StandardContactField::$LASTNAME,
    ],
    custom_fields:[
        'My custom field in Maileon',
    ]
);

if (!$getContact->isSuccess()) {
    die($getContact->getResultXML()->message);
}

$contact = $getContact->getResult();

/**
 * The contact object stores all information you requested.
 * 
 * Identifiers (Maileon ID, Maileon external id and email address), marketing permission
 * level, creation date and last update date are always included if they are set in Maileon.
 * 
 * ID: $contact->id
 * Email: $contact->email
 * Permission: $contact->permission->getType()
 * First name: $contact->standard_fields[StandardContactField::$FIRSTNAME];
 * Custom field: $contact->custom_fields['My custom field in Maileon'];
 */
```

--------------------------------

### Manage Transaction Types with TransactionsService

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Provides methods to list, retrieve, and delete transaction types and their associated transaction records. Timestamps for deletion must be provided in milliseconds.

```php
<?php
use de
xqueue
maileon
api
client
transactions
TransactionsService;
use de
xqueue
maileon
api
client
transactions
TransactionType;
use de
xqueue
maileon
api
client
transactions
AttributeType;
use de
xqueue
maileon
api
client
transactions
DataType;

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

$transactionsService = new TransactionsService([
    'API_KEY' => 'your-api-key-here',
]);

// Get all transaction types
$types = $transactionsService->getTransactionTypes(page_index: 1, page_size: 100);
foreach ($types->getResult() as $type) {
    echo "Type: " . $type->name . " (ID: " . $type->id . ")\n";
}

// Get transaction type by name
$orderType = $transactionsService->getTransactionTypeByName('order_confirmation');

// Get recent transactions for a type
$recentTransactions = $transactionsService->getRecentTransactions(
    type_id: 123,
    count: 100
);

// Get specific transaction by ID
$transaction = $transactionsService->getTransaction(
    type_id: 123,
    transaction_id: 'TXN-2024-001'
);

// Delete old transactions
$transactionsService->deleteTransactions(
    type_id: 123,
    before_timestamp: strtotime('-90 days') * 1000 // milliseconds
);
```

--------------------------------

### Manage Target Groups with Maileon API

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Provides functionality to create, retrieve, and delete target groups (distribution lists) for audience segmentation. Ensure the API key is correctly configured.

```php
<?php
use de\xqueue\maileon\api\client\targetgroups\TargetGroupsService;
use de\xqueue\maileon\api\client\targetgroups\TargetGroup;

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

$targetGroupsService = new TargetGroupsService([
    'API_KEY' => 'your-api-key-here',
]);

// Get all target groups
$result = $targetGroupsService->getTargetGroups(page_index: 1, page_size: 100);
foreach ($result->getResult() as $group) {
    echo "Target Group: " . $group->name . " (ID: " . $group->id . ")\n";
}

// Get target group count
$count = $targetGroupsService->getTargetGroupsCount()->getResult();
echo "Total target groups: $count\n";

// Get specific target group
$group = $targetGroupsService->getTargetGroup(123);

// Create new target group
$newGroup = new TargetGroup();
$newGroup->name = 'VIP Customers';
$targetGroupsService->createTargetGroup($newGroup);

// Delete target group
$targetGroupsService->deleteTargetGroup(123);

```

--------------------------------

### Handle Maileon API Errors Manually

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Configure the client to not throw exceptions and handle API errors manually using the MaileonAPIResult object. This allows for custom error logging and response processing.

```php
<?php
use de
amespace	olacklistslacklistsService;
use de
amespace	olacklistslacklistslacklistsAPIException;

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

$contactsService = new ContactsService([
    'API_KEY' => 'your-api-key-here',
    'THROW_EXCEPTION' => false, // Don't throw, handle errors manually
]);

try {
    $result = $contactsService->getContactByEmail('test@example.com');

    if ($result->isSuccess()) {
        $contact = $result->getResult();
        echo "Contact found: " . $contact->email . "\n";
    } else {
        // Handle API error
        $statusCode = $result->getStatusCode();
        $errorXml = $result->getResultXML();

        echo "Error Code: $statusCode\n";
        if ($errorXml && isset($errorXml->message)) {
            echo "Error Message: " . $errorXml->message . "\n";
        }
    }

    // Access response headers
    $requestId = $result->getResponseHeader('X-Request-Id');
    $allHeaders = $result->getResponseHeaders();

} catch (MaileonAPIException $e) {
    echo "API Exception: " . $e->getMessage() . "\n";
    echo "Status Code: " . $e->getCode() . "\n";
}
```

--------------------------------

### Unsubscribe Contact by Email using PHP

Source: https://context7.com/xqueue/maileon-php-api-client/llms.txt

Unsubscribes a contact from a specific mailing using their email address. Optional reasons can be provided for analytics. Ensure the API client and necessary classes are autoloaded.

```php
<?php
use de\xqueue\maileon\api\client\contacts\ContactsService;

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

$contactsService = new ContactsService([
    'API_KEY' => 'your-api-key-here',
]);

$result = $contactsService->unsubscribeContactByEmail(
    email: 'john.doe@example.com',
    mailingId: '12345',
    reasons: ['Too many emails', 'Content not relevant']
);

if ($result->isSuccess()) {
    echo "Contact unsubscribed successfully\n";
}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.