Skip to main content
The SDK throws typed exceptions that you can catch and handle.

​
Exception classes

The PHP SDK exports:
  • MailrifyException
  • AuthenticationException
  • ValidationException
  • NotFoundException
  • RateLimitException
  • ApiException

​
Catch typed exceptions

<?php

use Mailrify\Exceptions\ApiException;
use Mailrify\Exceptions\AuthenticationException;
use Mailrify\Exceptions\MailrifyException;
use Mailrify\Exceptions\NotFoundException;
use Mailrify\Exceptions\RateLimitException;
use Mailrify\Exceptions\ValidationException;
use Mailrify\Mailrify;

$client = new Mailrify($_ENV['MAILRIFY_SECRET_KEY']);

try {
    $client->contacts->get('missing-contact-id');
} catch (NotFoundException $error) {
    error_log('Contact not found');
} catch (ValidationException $error) {
    error_log('Validation failed: ' . $error->getMessage());
    error_log(json_encode($error->getErrorData()) ?: '{}');
} catch (AuthenticationException $error) {
    error_log('Check API key type or value');
} catch (RateLimitException $error) {
    error_log('Rate limited: ' . $error->getMessage());
} catch (ApiException $error) {
    error_log('Server/API error: ' . (string) $error->getStatusCode());
} catch (MailrifyException $error) {
    error_log('Mailrify SDK error: ' . $error->getMessage());
}

​
Key-type mismatch example

events->track() requires a public key and most other methods require a secret key. 
<?php

use Mailrify\Exceptions\AuthenticationException;
use Mailrify\Mailrify;

$secretClient = new Mailrify($_ENV['MAILRIFY_SECRET_KEY']);

try {
    $secretClient->events->track([
        'email' => '[email protected]',
        'event' => 'signup',
    ]);
} catch (AuthenticationException $error) {
    error_log($error->getMessage());
}

​
Retry and timeout behavior

The PHP SDK automatically retries transient failures:
  • Up to maxRetries retries (default 3)
  • Retries 429 and 5xx responses
  • Retries transport-level HTTP client failures
  • Uses Retry-After when present, otherwise exponential backoff with jitter
Timeout is configured in milliseconds with the timeout client option. 
<?php

use Mailrify\Mailrify;

$client = new Mailrify($_ENV['MAILRIFY_SECRET_KEY'], [
    'timeout' => 10_000,
    'maxRetries' => 1,
]);
The PHP SDK does not expose a retryAfter property on exceptions. Use the exception type, message, getStatusCode(), and getErrorData() for handling logic.