Email Subscriptions

Overview

Send platform alerts directly to a recipient's mailbox using Cybrid's email subscription system. Manage email subscriptions in the Partner Portal.

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 alerts that need to reach a person rather than a system: operational alerts for a finance team, and security notices about changes to your organization's subscriptions.

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

ℹ️

Same subscriptions, different delivery channel

Email and webhook subscriptions are managed together on the Developers → Subscriptions tab in the Partner Portal. The subscription type selects the delivery channel.

Authenticate with the Organization API

Use the Organization API

Subscription events and delivery records are in the Organization API, not the Bank API. Use Organization API endpoints to retrieve them.

Configure authentication scopes

Retrieve events and delivery records using an OAuth2 access token with organization-level scopes.

Required scopes:

⚠️

Subscription management requires the Partner Portal

API-key tokens cannot hold the subscriptions:read, subscriptions:write or subscriptions:execute scopes. If you request them, they are dropped and the token is issued with the remaining scopes. Calls to /api/subscriptions made with an API-key token return 403 with message_code: invalid_scopes. Create, view and delete subscriptions in the Partner Portal instead.

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": "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 — 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

Reserve health — alerts about the Partner Reserve Account balance:

Security notices — changes to the subscriptions in your organization, webhook and email alike:

An email subscription created in the Partner Portal receives every supported event type. To deliver alerts to more than one address, create one subscription per recipient.

ℹ️

Existing subscriptions keep their original events

Email subscriptions created before security notices were available were set to the two reserve-health event types, so they receive exactly what they received before. Create a new subscription to receive security notices.

ℹ️

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.

Register the recipient

Users with the Key Admin or Founder role can create and delete email subscriptions in the Partner Portal.

1. Sign in to the Partner Portal and select a production bank.
2. Open the Developers tab, then select Subscriptions.
3. Click Create Email Subscription.
4. Enter a descriptive name (max 128 characters) and the recipient email address (max 254 characters), then submit the form.

The Subscriptions tab shows each subscription's event filter, whether it is protected, and any pending deletion time.

⚠️

Email subscriptions are production-only

Email subscriptions cannot be created for a sandbox bank. 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. A subscription scheduled for deletion counts toward the limit until the deletion takes effect. Delete an unused subscription before creating a new one if you hit the limit.

Delete an email subscription

Deleting a subscription is scheduled rather than immediate, so an unexpected deletion can be noticed and investigated before it takes effect.

Delete a subscription from Developers → Subscriptions in the Partner Portal.

1. Deletion scheduled — scheduled_deletion_at is set on the subscription to 24 hours from the request. A subscription.deleting event is created.
2. Deliveries continue — The subscription keeps receiving events until the scheduled time.
3. Deletion takes effect — The subscription is removed and a subscription.deleted event is created.

Protect a subscription from deletion

A subscription with protection_enabled: true cannot be deleted, and the Partner Portal offers no delete action for it. protection_enabled is read-only; Cybrid enables it on request.

Protect the subscription that receives your security notices. Anyone who can delete subscriptions could otherwise silence the notices about their own misuse. Contact [email protected] to protect a subscription, or to remove protection when the subscription needs to change.

Organizations created in production start with a protected email subscription named Security notices, delivered to the email address of the user who created the organization. It receives every supported event type.

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.minimums.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

Example: subscription.deleted

Security notices identify the affected subscription by GUID and never contain links. They direct the reader to the Partner Portal to review the organization's subscriptions.

Subject: Security Alert: A Notification Subscription Was Deleted

Hello,

Notification subscription subscription_guid for organization organization_guid in the production
environment was deleted at 2026-01-24 12:00 UTC.

Events will no longer be delivered to it.

If you did not expect this change, review your organization's subscriptions:
1. Sign in to your Partner Portal
2. Select Developers from the menu
3. Select the Subscriptions tab

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

Regards,
Cybrid Technology

The other security notices follow the same layout:

Email delivery

Delivery workflow

1. Event occurs — A Partner Reserve Account balance crosses a threshold, or a subscription in your organization is created, fails, or is deleted.
2. Event created — A SubscriptionEvent record is created.
3. Email sent — Cybrid renders the template and sends the email to each email subscription whose event filter includes the event type.

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

When the Partner Portal rejects a new email subscription, it displays one of these errors:

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 with message_code: invalid_scopes
• Cause: Token lacks subscription_events:read, or an API-key token was used to call /api/subscriptions
• Fix: Request a token with subscription_events:read; manage subscriptions in the Partner Portal

Delivery failures

Throttled duplicate

• Cause: Repeats of the same event type to the same subscription within a five-minute window are suppressed. Reserve-health alerts send at most once per window; security notices send at most five times per window
• Result: No email is sent for the suppressed repeat
• 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.

Protect the security-notice recipient

Point a subscription at a mailbox your security team watches, and ask Cybrid to protect it. A protected subscription cannot be deleted, so the security notices (subscription.storing, subscription.failed, subscription.deleting, subscription.deleted) keep flowing even if credentials are misused.

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

The Partner Portal does not edit subscriptions. To change the recipient address, create the new subscription first, then delete the existing one. The old subscription keeps delivering for 24 hours after the delete request and counts toward the active limit until then.

If the organization already has 5 active email subscriptions, the create is rejected. Delete the existing subscription first, then create the replacement after the deletion takes effect 24 hours later. This leaves a gap in delivery to that recipient.

API reference summary

Subscription endpoints

The subscription endpoints back the Partner Portal and cannot be called with an API-key token. Manage subscriptions in the Partner Portal.

Event endpoints

Delivery endpoints

Key takeaways

• Manage in the Partner Portal — API-key tokens cannot create, view or delete subscriptions
• Use Organization API — Subscription events and deliveries are in the Organization API, not the Bank API
• Production only — Email subscriptions cannot be created in sandbox
• Curated event set — Reserve-health alerts (account.minimums.funding_pull.below_minimum, account.minimums.funding_pull.near_minimum) and subscription security notices (subscription.storing, subscription.failed, subscription.deleting, subscription.deleted) trigger emails today. The same events also fan out to webhook subscribers; see Webhooks.
• Deletion is delayed — Deleting a subscription schedules removal 24 hours out; deliveries continue and a subscription.deleting notice goes out in the meantime
• Protect the security recipient — A subscription with protection_enabled: true cannot be deleted; ask Cybrid to protect the one that receives security notices
• Inspect deliveries — Use the SubscriptionDelivery API to verify what was sent