Download the PHP package mycomm/mycomm-php without Composer

MyComm PHP SDK

The official PHP client for the MyComm messaging API: send and track messages, manage contacts and conversations, receive webhooks, and (for partners) provision customer accounts.

• Every operation of the public API and the partner API, with typed arguments and typed results
• Checks your arguments against the API's documented rules before sending, and tells you which field is wrong
• Retries that cannot double-send: every POST carries an Idempotency-Key
• Lists you can foreach over, across pages
• Webhook signature verification and a class per event
• A fake client for your own tests

Requires PHP 8.2 or later. Using Laravel? Install mycomm/mycomm-laravel instead: it adds configuration, a facade and a webhook route on top of this package.

Install

The SDK talks HTTP through any PSR-18 client. If your project has none yet:

Quick start

Create the key in the MyComm portal under Developers → API keys. Keep it on your server: never ship it in a browser or a mobile app.

How the SDK maps to the API

Each resource of the API reference is a property of the client and each operation a method. The reference names an operation with a verb in camelCase (sendMessage); the SDK groups the operations by resource, so the same call reads messages->send():

generator/config.php holds the full table of operation ids.

Arguments are named like the API's fields (reference_id, send_after), so the reference and your editor's autocompletion agree. Ids in the path come first; everything else is best passed by name.

Sending messages

Check what a send would do without sending it:

Send up to 1,000 messages in one call. Items are accepted or rejected one by one:

Follow a message afterwards with $mycomm->messages->show($id), or let MyComm tell you through webhooks.

What the SDK checks before sending

The API documents limits and rules for what you send: ranges, lengths, which fields exclude each other, which need another. The SDK checks them first, so a mistake fails at once with the field named, instead of as a 422 from the server:

The rules are generated from the API's OpenAPI document, so they follow the API. Nothing is sent when one fails. Rules the SDK does not know about, such as an opt-out, are still answered by the server (see Errors).

If the API relaxes a rule before you have updated the SDK, turn the checks off with new Client(..., validate: false). Values the API may add later (the enum of a response, an unknown error code) are never rejected.

Verify your settings

verify() checks that a key works and, when you give it a number to test with, that a message to that number would be accepted. It sends nothing: the second check is a dry run.

A dry run does not know whether the phone is online or whether the carrier delivers; a hold it can predict is in $result->holdReason. See the guide Verify your integration.

Lists and pagination

A list method returns one Page. Loop over it for the items of that page, or use all() to walk every page; the next page is fetched only when the loop reaches it.

$page->next_cursor, $page->hasMore() and $page->next() are there when you page by hand, and $page->autoPaging() does what all() does for lists that are not named list ($mycomm->conversations->messages($id)->autoPaging()).

Leaving a field out or clearing it

An update changes only the fields you pass. Where a field can be cleared, null clears it:

Errors

Every error answer of the API becomes an exception. Branch on code() (or errorCode, the same value as text), which is stable; the message says what happened and what to do, in English, and may change. echo $e and $e->summary() give one line with the code, status, message, details and request id.

All of them extend ApiException, which extends MyCommException, the base of everything the SDK throws. InvalidArgumentException also extends MyCommException, but it is not an ApiException: no request was made.

Retries and idempotency

The SDK retries a call twice (configurable) when the network fails, when MyComm answers 429 or 503 (waiting as long as Retry-After asks) and on other 5xx answers, with exponential backoff.

That is safe for sends because every POST carries an Idempotency-Key, and a retry repeats the same key: MyComm then replays the first answer instead of sending a second message. Pass your own key to make a whole operation of yours repeatable, for example across a queue job's attempts:

Webhooks

Verify each delivery with the signing secret of your webhook endpoint, then handle the typed event. Always pass the raw request body.

Good to know:

• Answer fast with any 2xx and do the work in a queue. MyComm waits 10 seconds, then retries.
• Deliveries can repeat and arrive out of order. De-duplicate on $event->id and never move a message status backwards.
• Rotating the secret: during the overlap MyComm signs with both secrets, so verification keeps working whichever one you hold. To switch without a gap, pass both: Webhook::constructEvent($payload, $header, [$new, $old]).
• An event type this SDK version does not know arrives as MyComm\Webhooks\UnknownEvent with data as an array. Answer 2xx.

Create the endpoint in the portal or with the API. The secret is shown once:

Partners

A partner key (mc_partner_...) provisions managed accounts and then acts as them on the normal API:

Or mint a key for the customer's own integration: $partner->partner->accountKeys->create($account->id, name: 'ERP').

Uploading files

Testing your code

MyCommFake gives you a real client that never touches the network. Every operation answers with the example of the API reference until you say otherwise.

FakeResponse also has page(), validationError(), noContent(), connectionError() and json(). To test your webhook receiver, MyComm\Testing\FakeWebhook::make('message.delivered', secret: $secret) gives you a signed payload and its MyComm-Signature header.

Configuration

When you pass your own HTTP client, set its timeout yourself: PSR-18 has no setting for it.

What every result carries

MyComm adds fields and values without a new API version. The SDK is built for that: a field it does not know yet is still in raw(), and an enum value it does not know arrives as a plain string instead of an enum case, so $channel->status === ChannelStatus::Active keeps working and nothing throws.

Versioning

The SDK follows semantic versioning. It is generated from the same OpenAPI documents that the API is tested against; CHANGELOG.md lists what each release added.

Contributing

Most of src/ is generated. See docs/development.md before changing anything.

License

MIT. See LICENSE.