birkly_send_mail

$result = birkly_send_mail(
    string $to,
    string $subject,
    string $html,
    array $opts = []
);

Options:

Option	Type	Description
alias	string	Alias to resolve (transactional_email, marketing_email, ops_alerts, custom).
text	string	Plain-text body. If omitted, a text version is generated from HTML.
from	string	Override From address.
from_name	string	Override From display name.
reply_to	string	Reply-To address.
attachments	array	Array of [name, mime, data] or file paths.
headers	array	Additional headers as key/value pairs.
idempotency_key	string	Prevents duplicate sends on retry.
sync	bool	true = send immediately; false = queue for async processing. Default depends on context.
connection_id	string	Bypass alias and use a specific Connection.

Return value:

Field	Meaning
ok	Whether the message was accepted/queued successfully.
status	queued, accepted, logged, failed, suppressed.
message_id	Provider or internal message id, when available.
error	Error message if ok is false.
stage	Pipeline stage that failed, for debugging.

birkly_notify

$result = birkly_notify(
    string $event,
    array $payload,
    array $opts = []
);

Looks up the route for $event in settings/connections/notification_routes.json and fans out to each configured channel. Options include sync and connection_id overrides. The return value is an array of per-channel results.

Built-in event keys:

• commerce.order_paid
• commerce.order_shipped
• form.submission
• user.password_reset
• user.email_verify
• system.health_alert
• team.invitation

Plugins may register custom keys as plugin_slug.event.

birkly_get_connection

$conn = birkly_get_connection(
    string $idOrAlias,
    array $opts = []
);

Resolves a Connection by id or alias. By default the returned array does not contain secrets. To include decrypted secrets, pass with_secrets => true; this requires the caller to hold the appropriate capability and should only be used inside server-side helpers.

Returned metadata includes:

Field	Description
id	Connection UUID.
name	Human label.
type	Connection type.
provider	Provider/transport slug.
config	Non-secret configuration.
health	Last health result.
managed_by_env	Whether env overrides are active.

birkly_list_connections

$connections = birkly_list_connections([
    'type' => 'email-transactional',
    'provider' => 'resend',
]);

Returns metadata for picker UIs. Never includes secrets.

birkly_connection_health

$health = birkly_connection_health('transactional_email');

Returns the stored health record and checklist for a Connection. Use this in admin dashboards and plugin empty states. Does not perform a live test; use the admin Test button or the REST API for that.

birkly_http_with_connection

$response = birkly_http_with_connection(
    string $idOrAlias,
    array $request
);

Applies the Connection’s auth mode to an HTTP request:

• bearer — adds Authorization: Bearer {secret} header.
• basic — adds Authorization: Basic {secret} header.
• header — adds a custom header with the secret.
• query — adds the secret as a query parameter.

$request fields:

Field	Description
method	HTTP method.
path	Path appended to the Connection base URL.
query	Query parameters.
headers	Extra headers.
body	Request body.
timeout	Request timeout in seconds.

The secret is applied inside the helper; plugin code never handles it directly.

birkly_verify_webhook

$verified = birkly_verify_webhook(
    string $endpointId,
    string $rawBody,
    array $headers
);

Verifies the signature on an incoming webhook payload using the signing secret stored for that endpoint. Returns true or false. On success, the caller is responsible for parsing the event and updating the delivery log or suppression list.

Provider-specific signature methods:

Provider	Header / mechanism
Resend	svix-signature
Postmark	X-Postmark-Signature
SES	SNS signature validation
Mailgun	X-Mailgun-Signature (timestamp + token + signature)

Admin REST endpoints

The admin REST API mirrors the PHP helpers:

Method	Endpoint	Purpose
GET	/api/admin/connections	List metadata.
POST	/api/admin/connections	Create Connection.
GET	/api/admin/connections/{id}	Read metadata.
PATCH	/api/admin/connections/{id}	Update config/secrets.
DELETE	/api/admin/connections/{id}	Delete Connection.
POST	/api/admin/connections/{id}/test	Test send / test request.
GET	/api/admin/connections/aliases	List alias mappings.
POST	/api/admin/connections/aliases	Update alias mapping.
GET	/api/admin/connections/delivery-log	Query log.
POST	/api/admin/connections/queue/drain	Process queued items.
POST	/api/webhooks/connections/{id}	Inbound provider webhook.

Exact REST paths and field names may be finalized when core implementation reports stable API names.

Plugin manifest contract

Plugins declare their needs in plugin.json:

{
  "requires_connections": [
    { "type": "email-transactional", "alias": "transactional_email", "optional": false },
    { "type": "slack-ops", "alias": "ops_alerts", "optional": true }
  ]
}

Hub uses this to warn admins before installing a plugin that needs a Connection that is not configured.