Starplex SDK

Send email

import { Starplex } from '@starchive/starplex-sdk';

const starplex = new Starplex({ secretKey: process.env.STARPLEX_SECRET_KEY! });

const { actionId } = await starplex.actions.sendEmail({
  from: '[email protected]',
  recipients: ['[email protected]'],
  subject: 'Welcome',
  text: 'Welcome aboard.',
  html: '<p>Welcome aboard.</p>',
  replyTo: '[email protected]',
});

• 1–100 unique recipients, each receiving a private copy.
• text is required. html and replyTo are optional.
• from is required and must be verified for your organization.

Options

Pass options as the second argument: sendEmail(message, options).

| Option | Use | | --- | --- | | idempotencyKey | Recover the same submission across calls. Keep recipients, order, and content unchanged. | | orgId | Required for global accounts only. | | signal | Abort the request, without cancelling the queued action. |

Automatic retries reuse the submission. A new call without a key starts a new action.

Verify a sender

await starplex.emailIdentities.verify('[email protected]'); // Sends the confirmation email.
// After clicking its link:
await starplex.emailIdentities.get('[email protected]'); // status: 'verified'

await starplex.actions.sendEmail({
  from: '[email protected]',
  recipients: ['[email protected]'],
  subject: 'Welcome',
  text: 'Welcome aboard.',
});

• Status: pending, verified, or failed; get returns null when absent.
• Call verify again to resend confirmation. Links expire after 24 hours.
• remove(address) disables sending; verify(address) restores access. Verified addresses need no new confirmation.
• Each address remains assigned to one organization, including after removal. Existing unmanaged SES identities cannot be claimed.
• Options: { orgId, signal }. Rights: resource.email-identity.create, .read, .delete.

Read results

const action = await starplex.actions.get(actionId);

if (action?.output?.kind === 'email') {
  console.table(action.output.recipients);
}

| Recipient status | Meaning | Details | | --- | --- | --- | | accepted | Provider accepted it; delivery unconfirmed. | providerMessageId | | rejected | Not sent. | code | | uncertain | May have been sent. A new key risks a duplicate. | code |

Results appear after completion. Failed actions expose action.error; request failures reject with StarplexError.

Subscribe to email.send.completed for a notification with actionId, orgId, and completedAt, then read the results using actions.get(actionId).

Required permissions: action.email.send to send, resource.action-run.read to read results.

import { Effect } from 'effect';
import { Starplex } from '@starchive/starplex-sdk/effect';

const starplex = new Starplex({ secretKey: process.env.STARPLEX_SECRET_KEY! });
const submission = starplex.actions.sendEmail({
  from: '[email protected]',
  recipients: ['[email protected]'],
  subject: 'Welcome',
  text: 'Welcome aboard.',
});

const { actionId } = await Effect.runPromise(submission);

Rerunning the same Effect reuses its submission. Use Effect interruption instead of signal.