Back to Arky

Notification

Send typed tenant emails through a mailbox and matching template

The Notification module sends typed tenant email actions to explicit recipients using a selected mailbox and a matching email template. Workflow send_email nodes use the same EmailSend contract.

Use Campaigns for Audience sends, broadcasts, and outreach sequences.

Send Email

POST /v1/notifications/email
SDK: sdk.notification.email.send() 
import type { EmailSendRequest } from 'arky-sdk';
import {
clearDurableRequest,
getOrCreateDurableRequest,
withDurableRequestLock
} from 'arky-sdk/utils';

const request: Omit<EmailSendRequest, 'send_id'> = {
send: {
type: 'contact_store_notification',
data: {
store_id: 'store_123',
template_id: 'tmpl_contact_notification',
mailbox_id: 'mailbox_123',
recipients: ['owner@example.com'],
vars: {
submission: { id: 'submission_123' },
},
},
}
};
const storageKey = 'arky:email-send:store_123:submission_123';

await withDurableRequestLock(storageKey, 'email send', async () => {
const durable = getOrCreateDurableRequest(storageKey, request, 'email send');
const response = await sdk.notification.email.send({
send_id: durable.id,
...request
});
clearDurableRequest(durable, 'email send');
return response;
});

Parameters

Name Type Description
send_id required UUID string Stable local identity for this logical send; reuse it only with the exact same send payload
send.type required EmailSend['type'] Transactional or operational email purpose. It must match the selected template type.
send.data.store_id required string Store ID
send.data.template_id required string Email template whose type matches the send type
send.data.mailbox_id required string Active tenant mailbox used as the sender
send.data.recipients required string | string[] Explicit recipient email address or addresses
send.data.vars optional Record<string, unknown> Template-specific Handlebars variables
Warning

Each recipient is a durable at-most-once provider effect. Reuse send_id when the same request is interrupted; never generate a new ID in an automatic retry. If Arky cannot prove the provider outcome, it records unknown and does not send the email again automatically. The OneSignal adapter’s deterministic RFC 9562 UUID idempotency key is defense-in-depth, not retry permission, and is never supplied by the client.

Note

Typed email send does not accept campaign_email, newsletter_email, or audience_id. Those sends must run through Campaigns so enrollment, suppression, membership, and unsubscribe rules are enforced.

For an Audience-backed newsletter_email, Campaigns requires a visible {{audience.manage_url}} and supplies mailbox transport with the matching RFC 8058 one-click unsubscribe header contract. Transactional sends do not receive subscription headers.

How Notifications Work

Default workflows use native send_email nodes with this same tagged enum:

  • Order created -> sends order confirmation to the contact and notification to the store
  • Service scheduled through an order -> uses the order workflow data
  • Form submitted -> sends the contact submission to the store
  • Audience confirmation -> sends the double opt-in confirmation to the subscriber

Every tenant email variant requires a mailbox in its typed payload. The backend rejects a template whose type does not match the requested email type.

Mailbox daily_limit is the campaign pacing ceiling. Successful transactional and support sends still increment sent_today, reducing that day’s campaign capacity, but critical non-campaign sends are not rejected by the campaign limit. External Google Workspace or SMTP-provider quotas apply separately.

Template Variables

Variables are passed as vars and rendered with Handlebars in the template subject, preheader, and HTML body.

const send = {
	type: "order_contact_notification",
	data: {
		store_id: "store_123",
		template_id: "tmpl_order_confirmation",
		mailbox_id: "mailbox_123",
		recipients: ["customer@example.com"],
		vars: {
			order: { number: "1001" },
		},
	},
};

Pass send through the durable-request pattern above.

See Email Templates for creating reusable templates and Campaigns for audience sends.