Email

The email proxy lets your deployed application send transactional emails through HiveForge's email delivery service. Emails are sent without embedding email provider API keys in your app, and credit usage is tracked automatically.

Access the email proxy via hiveforge.email.

import { HiveForgeClient } from '@producthacker/hiveforge-sdk';
 
const hiveforge = new HiveForgeClient({
  deploymentId: process.env.HIVEFORGE_DEPLOYMENT_ID!,
  deploymentSecret: process.env.HIVEFORGE_DEPLOYMENT_SECRET!,
});
await hiveforge.initialize();

Methods

`send(options)`

Send a transactional email through HiveForge's delivery service.

const result = await hiveforge.email.send({
  to: ['jane@example.com'],
  subject: 'Welcome to MyApp!',
  html: `
    <h1>Welcome, Jane!</h1>
    <p>Thanks for signing up. Here's how to get started...</p>
    <a href="https://myapp.com/onboarding">Start onboarding</a>
  `,
  text: 'Welcome, Jane! Thanks for signing up.',
  fromName: 'MyApp Team',
  replyTo: 'support@myapp.com',
  tags: { category: 'onboarding', user_id: 'usr_a1b2c3' },
});
 
console.log('Success:', result.success);
console.log('Message ID:', result.messageId);
console.log('Credits used:', result.creditsUsed);
console.log('Credits remaining:', result.creditsRemaining);

With CC and BCC:

await hiveforge.email.send({
  to: ['jane@example.com'],
  cc: ['manager@example.com'],
  bcc: ['audit@myapp.com'],
  subject: 'Your invoice is ready',
  html: '<p>Your invoice for March 2026 is attached.</p>',
});

Parameters (SendEmailOptions):

Parameter	Type	Required	Default	Description
`to`	`string[]`	Yes	--	Recipient email addresses (max 50)
`subject`	`string`	Yes	--	Email subject line
`html`	`string`	No	--	HTML email body
`text`	`string`	No	--	Plain text fallback body
`fromName`	`string`	No	Deployment default	Sender display name
`replyTo`	`string`	No	--	Reply-to email address
`cc`	`string[]`	No	--	CC recipients
`bcc`	`string[]`	No	--	BCC recipients
`tags`	`Record<string, string>`	No	--	Custom tags for tracking and analytics

⚠️

At least one of html or text must be provided. The SDK throws an EmailProxyException with code invalid_request if both are missing.

Returns (SendEmailResponse):

Field	Type	Description
`success`	`boolean`	Whether the email was accepted for delivery
`messageId`	`string?`	Unique message ID for tracking (may be undefined)
`creditsUsed`	`number`	Credits consumed for this email
`creditsRemaining`	`number`	Remaining credits after this send

Throws: EmailProxyException

Equivalent curl request

curl -X POST https://api.hiveforge.dev/api/v1/proxy/email/send \
  -H "Content-Type: application/json" \
  -H "X-Deployment-ID: d9f2a1b4-7c3e-4f8a-b5d6-1e2f3a4b5c6d" \
  -H "X-Deployment-Secret: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -d '{
    "to": ["jane@example.com"],
    "subject": "Welcome to MyApp!",
    "html": "<h1>Welcome!</h1>",
    "from_name": "MyApp Team",
    "reply_to": "support@myapp.com"
  }'

`getQuota()`

Get the email quota for your deployment including credits available and emails remaining.

const quota = await hiveforge.email.getQuota();
 
console.log(`Credits available: ${quota.creditsAvailable}`);
console.log(`Credits per email: ${quota.creditsPerEmail}`);
console.log(`Emails available: ${quota.emailsAvailable}`);
console.log(`Period ends: ${quota.periodEnds}`);

Returns (EmailQuotaResponse):

Field	Type	Description
`creditsAvailable`	`number`	Total credits available for email
`creditsPerEmail`	`number`	Credit cost per email sent
`emailsAvailable`	`number`	Number of emails that can be sent with current credits
`periodEnds`	`string`	Optional ISO timestamp when billing period ends

Error Handling

The EmailProxyException includes credit information when the error is credit-related:

import { EmailProxyException } from '@producthacker/hiveforge-sdk';
 
try {
  await hiveforge.email.send({
    to: ['jane@example.com'],
    subject: 'Hello',
    html: '<p>Hi!</p>',
  });
} catch (error) {
  if (error instanceof EmailProxyException) {
    console.error(`Email error [${error.code}]: ${error.message}`);
 
    if (error.creditsRequired !== undefined) {
      console.log(`Credits required: ${error.creditsRequired}`);
      console.log(`Credits available: ${error.creditsAvailable}`);
    }
  }
}

Types

import type {
  SendEmailOptions,
  SendEmailResponse,
  EmailQuotaResponse,
  EmailProxyError,
} from '@producthacker/hiveforge-sdk';

Credits Vectors