Download the PHP package meil/meil-php without Composer

meil-php

The official PHP client for the meil.ro API: transactional email and newsletters.

• PHP 8.1 or newer. It needs only ext-curl and ext-json, so it runs on shared hosting and inside WordPress.
• Answers are plain associative arrays. They are described with PHPDoc array shapes, so your editor and PHPStan know every key.
• Safe retries: sends always carry an Idempotency-Key, so a retry never sends twice.

Keys are the API's own field names (reply_to, template_id, audience_id), so the API docs and this package read the same.

Sending email

With a saved template and its placeholders:

With attachments. Pass the file's raw bytes as content, and the SDK base64-encodes them. Do not encode them yourself. You can attach up to 20 files, 7 MB in total.

The answer is ['id' => ...]. It can also have unsubscribe_url, and suppressed when some recipients on your suppression list were skipped.

Idempotency keys

emails->send() and broadcasts->create() always send an Idempotency-Key. If you give none, the SDK makes a random UUID for the call, which makes its own retries safe. To make your own retries safe too (a cron job or queue worker that runs twice, say), pass a key that is unique to the send:

For 24 hours, the same key with the same body returns the first answer and sends nothing new. The same key with a different body throws a ConflictException with the error name invalid_idempotent_request.

Errors

Failed calls throw. Every exception is a Meil\Exception\MeilException (a RuntimeException) with these methods:

• getErrorName(): the API's stable error name, such as "rate_limit_exceeded";
• getStatusCode(): the HTTP status;
• getMessage(): English text for people;
• getId(): when there is one.

Retries

By default the SDK retries up to 2 times. Set max_retries to change that; 0 turns retries off.

It retries:

• 429 rate_limit_exceeded, after the Retry-After the API sends;
• 409 concurrent_idempotent_requests;
• network errors and timeouts;
• 502, 503, 504, and Cloudflare's 520 to 524, with exponential backoff.

Quotas (daily_quota_exceeded, monthly_quota_exceeded, previous_broadcast_pending) are never retried. GET, PATCH and DELETE calls are retried. A POST is retried only when it carries an Idempotency-Key, which means only emails->send() and broadcasts->create().

The SDK waits between retries with usleep(), so a web request that hits a rate limit can take a few extra seconds. For a page that must answer quickly, set 'max_retries' => 0.

Broadcasts

$meil->broadcasts->send($id) sends a draft. It can also return the under_review result.

Other broadcast methods: get, list, update, delete, schedule($id, $date) and unschedule.

Contacts

The SDK URL-encodes the email addresses in paths for you.

Paging

emails->list() and audiences->listContacts() return one page: ['object' => 'list', 'has_more' => bool, 'data' => [...]]. To get everything, loop over the generator. Pages are fetched as you go:

The other lists (audiences->list(), broadcasts->list(), templates->list()) return everything at once.

All methods

A key's scope decides what it may call. email_access keys get emails and the content check; broadcast_access keys get everything except audiences and contacts. The SDK does not check scopes: the API answers with a PermissionException (insufficient_permission).

Timestamps

Timestamps in answers (created_at, scheduled_at, sent_at, ...) are UTC strings formatted "YYYY-MM-DD HH:MM:SS", returned as the API sends them. To parse one: new DateTimeImmutable($email['created_at'], new DateTimeZone('UTC')).

WordPress and shared hosting

The package has no Composer dependencies. Without Composer, require the files with a small PSR-4 autoloader for the Meil\ namespace, which maps to src/:

To send through something other than cURL (WordPress's HTTP API, a PSR-18 client), implement Meil\Transport\TransportInterface and pass it as the transport option.

Development

License

MIT