PHP SDK

A PHP client for the API that does the encryption the Mailcycle apps do, on your machine. With it a program can create addresses that receive mail, open what arrives, and send. The recovery phrase never leaves the machine it runs on.

It needs PHP 8.1 or later, with the sodium, openssl, curl, json and mbstring extensions, which most builds include. It has no other dependencies.

composer config repositories.mailcycle composer https://mailcycle.email/php
composer require mailcycle/mailcycle

The package is served from Mailcycle’s own Composer repository, which the first line adds to your project.

Sign in

use Mailcycle\Mailcycle;

$mc = Mailcycle::signIn(getenv('MAILCYCLE_PHRASE'));

This is the same handshake the apps use: nothing secret crosses the wire, and it works on every plan.

With an API key instead, on Operator and up:

$mc = Mailcycle::withApiKey(
    getenv('MAILCYCLE_API_KEY'),
    getenv('MAILCYCLE_PHRASE') ?: null,   // null to manage without opening mail
);

Without the phrase a client can manage addresses, devices and metadata, but cannot open mail or create an address that receives it, because the address’s key is derived from the phrase. With both, the phrase is checked against the key’s account before anything is opened.

Each signIn opens a 30-day session. Keep $mc->sessionToken() somewhere private and pick it up with Mailcycle::resume($token, $phrase) rather than signing in on every run. Each of these takes an optional Options last, for a longer timeout: new Options(timeoutSeconds: 60).

Addresses

use Mailcycle\NewAddress;

$address = $mc->addresses()->create(new NewAddress(prefix: 'signup', label: 'Test run 42'));

$all = $mc->addresses()->list();

The public half of the address’s key goes up with the request so the mail server can seal what arrives; the private half stays on your machine. The label is sealed locally, and the server stores it as ciphertext.

With no prefix or localPart, the server rolls a name like quiet_falcon. Set style to choose the kind:

use Mailcycle\NameStyle;

$address = $mc->addresses()->create(new NewAddress(style: NameStyle::Person));   // maya.holt

The styles are Person, Business, Team and Neutral, the default. style is ignored when prefix or localPart is set.

To pick a name before creating, roll a few:

$names = $mc->addresses()->rollNames(NameStyle::Business);   // up to 8, like harbor-supply42

$address = $mc->addresses()->create(new NewAddress(localPart: $names[0]));

A rolled name works as localPart on every plan; any other name needs Scale and up. The names are free when rolled, but someone can take one before you create it, and then create is refused. Pass a domain second to roll for it; leave it out to use the one create would.

Reading mail

$messages = $mc->messages()->all($address->id);
foreach ($messages as $message) {
    echo $message->fromAddress, ' ', $message->subject, "\n";
}

$data = $mc->messages()->attachment($messages[0], 0);   // the bytes, opened locally

A message that will not open, because there is no phrase or it is the wrong one, comes back with opened false and empty content rather than an exception, so one unreadable message does not hide the rest of a page.

$message->html is the HTML as the sender wrote it. $message->safeHtml has every remote image, stylesheet and embed removed, as the apps do it, and is the one to render; $message->blocked lists what was taken out.

Waiting for a message

use Mailcycle\WaitFor;

$code = $mc->messages()->waitFor(new WaitFor(addressId: $address->id, subject: 'verification'));

Listens on the event stream where it is available and polls the address otherwise, and returns the message opened. If nothing matching arrives in time it throws an ApiException with the code timeout. Mail received from since on counts, even if it landed before the stream was up; it defaults to now, so to wait for a reply to something you are about to send, take the time before sending.

Sending

use Mailcycle\Outgoing;

$mc->messages()->send(new Outgoing($address->emailAddress, 'someone@example.com', 'Hello', 'Hi'));

Set replyTo to the message you are answering to thread a reply. A session can send from Personal up; an API key on Scale and up. Free receives only.

send returns a SendResult: messageId is the Message-ID header, and sentCopyId is the id of the copy in Sent, which the other message calls take, or null when the address keeps none.

Attachments take raw bytes and the client encodes them. A message can carry up to ten files, 3.5 MB between them. Give a file a contentId to show it inline, where the HTML says cid: and that id. Program and script files, like .exe and .js, are refused.

use Mailcycle\OutgoingAttachment;

$mc->messages()->send(new Outgoing(
    $address->emailAddress,
    'someone@example.com',
    'Your invoice',
    'Attached.',
    html: '<img src="cid:logo"><p>Attached.</p>',
    attachments: [
        new OutgoingAttachment('invoice.pdf', file_get_contents('invoice.pdf'), mimeType: 'application/pdf'),
        new OutgoingAttachment('logo.png', file_get_contents('logo.png'), mimeType: 'image/png', contentId: 'logo'),
    ],
));

Events and webhooks

$stream = $mc->events()->stream();
while (($event = $stream->nextEvent()) !== null) {
    echo $event->type, "\n";
}

The stream does its work while you read it: nextEvent() connects, answers the server and reconnects after a drop. Pass it a timeout in seconds where a quiet stream should not block forever. Events carry ids, never content, and are not replayed after a drop, so Hooks onReconnect, passed to stream(), is where to refetch what you are showing.

To check a webhook came from Mailcycle, pass the body exactly as it arrived:

use Mailcycle\WebhookSignature;

WebhookSignature::verifyNow($secret, file_get_contents('php://input'), $_SERVER['HTTP_MAILCYCLE_SIGNATURE'] ?? null);

API keys

$created = $mc->apiKeys()->create('Deploy script');
echo $created->token, "\n";   // shown once; keep it somewhere private

foreach ($mc->apiKeys()->list() as $key) {
    echo "{$key->id} {$key->name} ...{$key->hint}\n";
}
$mc->apiKeys()->revoke($created->apiKey->id);

Listing, creating and revoking keys need a signed-in session, so a leaked key cannot make more of itself. The name is sealed on your machine, and the server stores it as ciphertext. A name that will not open comes back as null.

signOut() on a client built with an API key does nothing. A key is not a session; it works until it is revoked.

Webhooks

use Mailcycle\WebhookUpdate;

$created = $mc->webhooks()->create('https://example.com/hooks/mail', ['message.received'], 'Orders');
$secret = $created->secret;   // shown once, for checking signatures

$mc->webhooks()->update($created->webhook->id, new WebhookUpdate(enabled: false));
$mc->webhooks()->test($created->webhook->id);

$page = $mc->webhooks()->deliveries($created->webhook->id);
foreach ($page->deliveries as $delivery) {
    echo "{$delivery->eventType} {$delivery->status} {$delivery->responseStatus}\n";
}

Webhooks are on Operator and up. list() returns the webhooks with their names opened, and every event type one can ask for. rotateSecret returns a new secret once, and redeliver sends a logged event again with the same event id. Adding, changing, rotating and removing need a signed-in session; an API key can list, test, read deliveries and redeliver.

Sessions

foreach ($mc->sessions()->list() as $session) {
    echo "{$session->id} {$session->expiresAt} ", $session->current ? 'this one' : '', "\n";
}
$mc->sessions()->revokeOthers();

revoke($id) ends one session. All three need a signed-in session.

Deleting the account

$mc->deleteAccount();

Erases the account and everything in it at once, with no grace period. Its addresses are retired and never issued again. It needs a signed-in session. If the account balance still holds money you paid in, it is refused with balance_held: ask for the balance back through support first.

$mc->subscription() returns the plan, renewal date and balance, and $mc->plans() lists every plan.

Pairing devices

// The text of the device's QR code, or the eight digits it shows.
$device = $mc->devices()->pair('MC1:12345678:...', 'Kitchen Pi');

$mc->devices()->assign($device->id, $address->id);     // hands the keys over too
$mc->devices()->unassign($device->id, $address->id);
$mc->devices()->handOverKeys($device->id);             // again, on its own

This is what the app’s Add device screen does, done by a script. It needs the phrase and a signed-in session. The name is sealed on your machine.

Each device has a wrap secret, and its address keys are sealed under it. The account keeps a copy in the device’s sealed profile, so keys can be handed over again when an address is assigned or taken off.

There are two ways the secret gets here. The QR code carries the device’s own secret, so it never passes through Mailcycle. The eight digits carry no secret, so the client makes one and seals it to a key the device published. The server relays that key, so it could put its own in its place at pairing and read the keys that follow. The QR path does not have that gap. Use it where you can.

A device on an older build publishes no key. Pairing it by its digits fails with an error that says to pair it in the app, or pass its QR code instead.

Errors

Everything throws a Mailcycle\Exception\MailcycleException. An API failure is an ApiException carrying the HTTP status() and the API’s own code in apiCode(), which is what to match on.

use Mailcycle\Exception\ApiException;

try {
    $mc->messages()->send($outgoing);
} catch (ApiException $e) {
    if ($e->apiCode() === 'rate_limited') {
        // back off
    }
}

How the encryption is checked

It is checked against the published test vectors, including the refusals.