Email API

Send any email from your own server with a single REST call. Receipts, notifications, magic links, digests — anything your app needs — delivered through your project's configured SMTP.

The Email API is the programmatic counterpart to OrbitNest's built-in auth emails. Give it a recipient, subject, and body, and it sends through the SMTP provider you configured for the project.

Service-role only

This endpoint requires your project's service-role key, never the anon key. Call it from a trusted server, an edge function, or a background job — never from client-side code where the key would be exposed.

Endpoint

bash

POST https://studio.orbitnest.io/api/project/{slug}/email/send

Authenticate with the service-role key in the standard header:

Authorization: Bearer <service_role_key>
Content-Type: application/json

Send an email

bash

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

Body fields

to — recipient email address (required).
subject — subject line (required).
html — HTML body (required).
text — plain-text fallback (optional but recommended for deliverability).

From an edge function

A common pattern is to trigger email from server-side logic — for example, sending a confirmation after a database write. Because edge functions run with trusted access, you can call the Email API directly:

javascript

export default async function handler(req) {
  const { email, orderId } = req.body;

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

  return { ok: true };
}

Deliverability tips

Always include a text part — HTML-only mail scores worse with spam filters.
Send from a verified domain with SPF, DKIM, and DMARC configured.
Keep transactional and marketing sends on the same authenticated domain so reputation accrues.
Configure your SMTP first — see Email & SMTP.

Need bulk sends?

The Email API sends one message per call. To reach many of your project's users at once with audience targeting, use Email Marketing instead.