Email API

The Email API sends one email per call through the SMTP server configured for your project. It always needs project SMTP. Use it for receipts, notifications and other app emails sent from your own backend or from an edge function.

Endpoint

POST https://api.orbitnest.io/api/project/:slug/email/send
Authorization: Bearer <service_role_key>
Content-Type: application/json

:slug is your project slug, for example my-app. The path uses project (singular).

Request body

Responses

Send an email

curl -X POST "https://api.orbitnest.io/api/project/my-app/email/send" \
  -H "Authorization: Bearer $ORBITNEST_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your receipt from My App",
    "html": "<h1>Thanks!</h1><p>Order #1234 is confirmed.</p>",
    "text": "Thanks! Order #1234 is confirmed."
  }'

From a Node.js server

None of the SDKs has an email method, so call the endpoint with fetch:

const res = await fetch('https://api.orbitnest.io/api/project/my-app/email/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.ORBITNEST_SERVICE_KEY}`,
  },
  body: JSON.stringify({
    to: 'customer@example.com',
    subject: 'Your receipt from My App',
    html: '<p>Order #1234 is confirmed.</p>',
  }),
});

if (!res.ok) {
  const { message } = await res.json();
  throw new Error(`Email failed: ${message}`);
}

From an edge function

Edge functions do not get the service-role key automatically. Add it as a project environment variable named ORBITNEST_SERVICE_ROLE_KEY first, then read it with Deno.env.get:

export default async function handler(req: Request) {
  const { email, orderId } = await req.json();

  const res = await fetch('https://api.orbitnest.io/api/project/my-app/email/send', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${Deno.env.get('ORBITNEST_SERVICE_ROLE_KEY')}`,
    },
    body: JSON.stringify({
      to: email,
      subject: 'Order confirmed',
      html: `<p>Your order #${orderId} is on its way.</p>`,
    }),
  });

  return new Response(await res.text(), {
    status: res.status,
    headers: { 'Content-Type': 'application/json' },
  });
}

Behavior and limits

• Requires project SMTP. The email goes through the project's SMTP settings. If SMTP is not configured or is turned off, the call fails with 400 and a message containing PROJECT_SMTP_NOT_CONFIGURED. The shared OrbitNest sender only carries auth emails and is never used here.
• Public SMTP hosts only. If the configured host is or resolves to a private or internal address, the call fails with 400. See Allowed hosts.
• One recipient per call. There are no cc, bcc, attachment, custom header, From or Reply-To fields.
• Fixed sender. The From address is the project's From Name and From Email. Reply-To is the From Email.
• No templating. subject and html are sent exactly as given. {{variable}} placeholders are not replaced, and email templates only apply to auth emails.
• Synchronous. The call returns once your SMTP server accepts or rejects the message. There is no queue, retry or delivery log.
• No OrbitNest rate limit. Only your SMTP provider's sending limits apply.

To email many users at once, use Email marketing.

In Studio

The endpoint, the service-role key (masked, with a copy button) and the request fields are shown in the Email API panel of your project's Settings → Marketing page.