Email & SMTP

Email on OrbitNest spans three jobs — transactional auth emails, your own programmatic sends, and marketing broadcasts. They all flow through one place: your project's SMTP configuration.

Every OrbitNest project routes outbound email through an SMTP provider you control. Point it at Amazon SES, Postmark, SendGrid, Mailgun, or any SMTP relay, and OrbitNest uses it for authentication emails, the Email API, and marketing broadcasts alike.

The three jobs email does

Transactional

OTP codes, password resets, and welcome emails sent automatically by auth flows. Customize them with Email Templates.

Programmatic

Send any email from your own backend with the Email API using your service-role key.

Marketing

Broadcast to segmented audiences of your project's users with Email Marketing.

Bring your own SMTP

If no custom SMTP is configured, OrbitNest falls back to a shared system sender so things work out of the box during development. For any production app you should configure your own SMTP — it gives you control over deliverability, your sender domain, and reputation, and it lets emails come from your brand rather than a shared address.

Credentials are encrypted at rest and never returned in plaintext by the API.

Configure SMTP

Set SMTP from Project Settings → SMTP in the Studio, or via the REST API. You'll need the host, port, username, password, and the from-name / from-email that recipients should see.

bash

curl -X PUT \
  https://studio.orbitnest.io/api/projects/{projectId}/smtp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "email-smtp.us-east-1.amazonaws.com",
    "port": 587,
    "secure": false,
    "username": "AKIA...",
    "password": "your-smtp-password",
    "from_email": "hello@yourdomain.com",
    "from_name": "Your App",
    "enabled": true
  }'

Ports & TLS

587 with secure: false — STARTTLS (most common, recommended).
465 with secure: true — implicit TLS.

Example: Amazon SES

SES is a popular, low-cost choice. Create SMTP credentials in the SES console (an AKIA… username plus a generated password), then verify your sending domain or address. A few things to know:

The SMTP password is region-derived — the host region must match where you created the credentials (e.g. email-smtp.us-east-1.amazonaws.com).
Your from_email domain or address must be a verified identity in SES.
While your account is in the SES sandbox, recipients must also be verified. Request production access to send to anyone.

Send a test email

Verify your configuration before going live. The test endpoint connects with your saved credentials and delivers a sample message:

bash

curl -X POST \
  https://studio.orbitnest.io/api/projects/{projectId}/smtp/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "test_email": "you@example.com" }'

Check spam on first sends

A brand-new sender domain has no reputation yet, so early emails can land in spam. Set up SPF, DKIM, and DMARC for your domain (your SMTP provider documents these) to maximize inbox placement.

Reset to default

Delete the SMTP configuration to revert to the shared system sender:

bash

curl -X DELETE \
  https://studio.orbitnest.io/api/projects/{projectId}/smtp \
  -H "Authorization: Bearer $TOKEN"