Download the PHP package duva-mail/duva without Composer

Duva for PHP

The official Duva client library for PHP. Duva is a transactional email API hosted in Canada.

Requires PHP 8.2 or later.

Sending a message

Reading events and pagination

events->list() and suppressions->list() return one page (->data, ->nextCursor); events->listAll() and suppressions->listAll() return a Generator that follows nextCursor for you, without ever loading every page into memory, optionally bounded with maxItems:.

Verifying a webhook

$rawBody must be the exact bytes Duva sent (file_get_contents('php://input'), not a re-serialized parsed body): re-encoding it changes the bytes and invalidates the signature. Rotating your webhook secret? Pass an array — Webhooks::constructEvent([$old, $new], ...) — while both are active.

Errors

Every error Duva answers with is a Duva\Exceptions\DuvaException subclass; rely on ->errorCode (the contract), never on the exception message (its wording can change):

Network failures and timeouts throw Duva\Exceptions\ConnectionException / TimeoutException instead (no HTTP response was ever received). Reads and messages->send() (idempotency-key protected) are retried automatically on a transient failure; suppressions->add()/remove() and webhooks->create()/delete() are not, because the outcome of a timed-out first attempt is unknown. A 429 quota_exceeded is never retried automatically (its retryAfter can be hours); a 429 rate_limited is, as long as the wait fits within maxRetryWaitSeconds (30s by default).

Attachments

Attachment::fromBytes($filename, $content, contentType: null, contentId: null) works from data already in memory; contentId turns the attachment into an inline image the HTML references with cid:.

Testing your own application

Duva\Http\TestTransport records every RequestSpec sent and lets you script the responses: no network call, no separate HTTP mocking library required.

Configuration

Only psr/http-client, psr/http-message and psr/http-factory (interfaces) are hard dependencies. Without an injected transport:, the client builds a default one from guzzlehttp/guzzle (composer require guzzlehttp/guzzle if you haven't); to use a different PSR-18 client instead, wrap it in Duva\Http\Psr18Transport yourself and pass it as transport:.

Full reference

The complete API surface and the OpenAPI specification this library follows: https://duva.ca/en/docs and https://duva.ca/openapi.json.

Development

Response types are hand-written value objects (src/Models/, readonly classes): PHP is the other language in docs/bibliotheques-clientes.md §4/§5 (besides Ruby) without an idiomatic single-purpose "models from OpenAPI" generator — openapi-generator's PHP output is verbose, mutable getter/setter/ArrayAccess classes, not the strict readonly types this library targets. The client itself (retries, pagination, errors, webhooks) is checked against the shared fixtures published in duva-mail/duva-conformance.

License

MIT, see LICENSE.