Email Subscriptions

Overview

Send platform alerts directly to a recipient's mailbox using Cybrid's email subscription system. Manage email subscriptions through the Organization API.

Email subscriptions are a second flavor of subscription alongside webhooks. Where a webhook subscription delivers a JSON payload to an HTTPS endpoint, an email subscription delivers a human-readable email to a recipient address. Use email subscriptions for operational alerts that need to reach a person (for example, a finance team) rather than a system.

To enable email events, register one or more email recipients. Cybrid sends an email each time a supported event occurs.

ℹ️

Same API, different delivery channel

Email subscriptions share the /api/subscriptions endpoints with webhooks. The type field on the request body selects the delivery channel.

Authenticate with the Organization API

Use the Organization API

All email subscription operations are in the Organization API, not the Bank API. Use Organization API endpoints for all email subscription operations.

Configure authentication scopes

Interact with email subscriptions using an OAuth2 access token with organization-level scopes.

Required scopes:

Get an Organization token

Create an Organization Application in the IDP service, then request an OAuth2 token using client credentials flow:

POST https://id.{environment}.cybrid.app/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "client_id",
  "client_secret": "client_secret",
  "scope": "subscriptions:read subscriptions:execute subscription_events:read"
}

{
  "access_token": "access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the access token in all Organization API requests:

Authorization: Bearer {access_token}

⚠️

Common authentication errors

• 401 Unauthorized: Invalid or expired token
• 403 Forbidden: Token lacks required scopes
• Using a bank token instead of organization token will not work

Subscribe to email events

Cybrid sends an email each time a supported event occurs in your organization. Each event creates a new SubscriptionEvent object. Each email subscription that matches receives its own delivery record.

Email subscriptions support a curated subset of platform events — operational alerts that benefit from human attention. Other event types (trades, transfers, identity verifications) are delivered only to webhook subscriptions and are skipped for email subscriptions.

Supported event types

Events related to Partner Reserve Account balance health:

Every email subscription receives every supported event type — there is no per-subscription event-type filter. To deliver alerts to more than one address, create one subscription per recipient; each will receive the full set of supported events.

ℹ️

Event coverage expands over time

The list of email-supported event types is curated. Webhook subscriptions receive a much broader set of events (trade, transfer, identity verification). Use webhooks for programmatic integration; use email subscriptions for human-facing alerts.

Create an email subscription

Unlike a webhook, an email subscription does not require you to host an endpoint. Register the recipient address and the subscription is active immediately.

ℹ️

Manage email subscriptions in the Partner Portal

Users with the Key Admin or Founder role can create and delete email subscriptions from the Developers → Subscriptions tab in the Partner Portal.

Register the recipient

Register the recipient address using the Subscription API so Cybrid knows where to deliver alerts.

Endpoint: POST /api/subscriptions

Request parameters:

Request example:

POST /api/subscriptions
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "name": "Reserve Health Alerts",
  "type": "email",
  "recipient": "[email protected]",
  "environment": "production"
}

{
  "guid": "subscription_guid",
  "organization_guid": "organization_guid",
  "name": "Reserve Health Alerts",
  "recipient": "[email protected]",
  "environment": "production",
  "type": "email",
  "state": "completed",
  "created_at": "2026-01-24T12:00:00Z",
  "updated_at": "2026-01-24T12:00:00Z"
}

⚠️

Email subscriptions are production-only

Email subscriptions cannot be created with environment: sandbox. Use webhook subscriptions to verify event flow in sandbox first, then add email subscriptions on top in production for human-facing alerts.

ℹ️

Active subscription limit

You can register up to 5 active email subscriptions per organization. Delete an unused subscription before creating a new one if you hit the limit.

Understand the email contents

Cybrid sends plain-text emails from [email protected] to the registered recipient. The subject and body depend on the event type that triggered the delivery.

Sender and headers

Example: account.balance_funding_pull.below_minimum

Subject: Urgent Action Required: ACH Hold Due to Reserve Account Balance Below Minimum

Dear Acme Bank Finance Team,

This is a notification that your Partner Reserve Account balance of 5,000.00 USD is below
the required minimum of 10,000.00 USD.

Please take immediate action by sending funds to your Partner Reserve deposit account. Until your
Partner Reserve account is topped up to the minimum balance or higher, there will be a 2-day hold
in effect on ACH pulls.

Please contact [email protected] if you have any questions.

Regards,
Cybrid Technology

Email delivery

Delivery workflow

1. Event occurs — A Partner Reserve Account balance crosses a threshold.
2. Event created — A SubscriptionEvent record is created.
3. Email sent — Cybrid renders the template and sends the email.

Delivery states

Inspect deliveries

Use the SubscriptionDelivery API to inspect individual email deliveries. The response field on each delivery record contains either a provider message identifier on success, or one of these values on failure:

Subscription health

Cybrid tracks per-subscription delivery health using deliveries_failing_since. This field is set when a delivery fails and the subscription was previously healthy, and cleared when a later delivery succeeds. If deliveries continue to fail for an extended period, the subscription transitions to state: failed and stops receiving further deliveries.

To re-enable a failed subscription, delete it and create a new one.

Common errors and troubleshooting

Subscription creation errors

Errors are returned with HTTP status, a message_code, and an error_message. Developers should switch on message_code first; when message_code is overloaded (as with invalid_parameter), use error_message to disambiguate.

ℹ️

Email subscription availability

Email subscriptions are gated per organization. If your first POST /api/subscriptions with type: email returns 501, contact Cybrid support to enable the feature for your organization.

Authentication errors

Wrong token type

• Symptom: 403 Forbidden
• Cause: Using a bank token instead of an organization token
• Fix: Get an organization-scoped OAuth token

Missing scopes

• Symptom: 403 Forbidden
• Cause: Token lacks subscriptions:execute scope
• Fix: Request a token with subscriptions:execute for create and delete

Delivery failures

Throttled duplicate

• Cause: A duplicate of a recent delivery for the same event type was suppressed
• Result: No email is sent for the duplicate
• Fix: Expected behavior. If you need finer-grained alerting, use a webhook subscription

Email delivery failed

• Cause: The email provider rejected the send
• Result: Delivery marked failed
• Fix: Verify the recipient address is correct and reachable

Follow best practices

Use a distribution list

Point the recipient at a team distribution list (for example, [email protected]) rather than an individual mailbox. This avoids missed alerts when a single person is on leave and keeps the recipient stable across staff changes.

Treat emails as alerts, not source of truth

Emails are intended to draw human attention. Use the Bank API to fetch the authoritative state of the underlying object (for example, the Partner Reserve Account balance) before taking action.

Allowlist the sender

Configure the recipient mailbox or distribution list to allowlist [email protected] so alerts do not land in spam.

Combine email with webhooks

Use webhooks for programmatic handling (for example, posting to an internal incident channel) and email subscriptions for human-facing escalation. Both subscription types can co-exist on the same organization and the same events.

Rotate recipients by deleting and recreating

There is no PATCH on subscriptions. To change the recipient address, delete the existing subscription and create a new one.

API reference summary

Subscription endpoints

Event endpoints

Delivery endpoints

Key takeaways

• Use Organization API — Email subscriptions are in the Organization API, not the Bank API
• Get Organization token — Use OAuth2 with subscriptions:execute scope
• Production only — Email subscriptions cannot be created in sandbox
• Curated event set — Only Partner Reserve Account balance events trigger emails today
• Inspect deliveries — Use the SubscriptionDelivery API to verify what was sent