Email notification API

1. Overview

The Nexus notification service sends emails (and optionally SMS) on behalf of your applications. Use this documentation to understand the API contract and how to integrate your backend with Nexus.

Works with any language. The Nexus API is a standard HTTP API that accepts JSON. You can call it from Node.js, Python, Ruby, PHP, Go, Java, C#, Elixir, or any language that can send HTTP requests — no SDK required. The same endpoint and request format apply everywhere; only the syntax of your HTTP call changes.

• Endpoint: POST /api/v1/notifications

• Auth: Authorization: Bearer <client_api_key>

• Email body and subject support placeholders: {{variable_name}}. Replace them by sending a data (or variables) object in the request with matching keys.

Your app does not send SMTP mail itself. Instead:

1. You create a project in the Nexus dashboard
2. Nexus gives you an API key
3. You put that key in your backend project
4. Your app sends a short JSON request
5. Nexus fills in a template and delivers the email

Example payload:

{
  "template": "password_reset",
  "to": "user@example.com",
  "data": {
    "user_name": "Jane",
    "email": "user@example.com",
    "password": "TempPass123"
  }
}

2. Before you start

Sign in to the Nexus dashboard and have a backend project ready. Store your API key on the server only — never in a browser or mobile app.

3. Create a project

A project is one application or environment that will send email through Nexus.

1. Sign in to the Nexus dashboard
2. Open Projects
3. Click Add Project
4. Enter a clear name, such as My App - Production or My App - Staging
5. Fill in the contact email and any from-address details
6. Save the project

Create a separate project for each environment. That keeps API keys and templates from mixing.

Examples:

• My App - Production

• My App - Staging

4. Generate an API key

When you create a project, Nexus generates an API key automatically. Copy it immediately — it may not be shown again in full.

To get a new key later:

1. Open the project
2. Find the API Key section
3. Click Regenerate API Key
4. Copy the new key and update your project

Treat the key like a password:

• Do not put it in frontend code

• Do not commit it to git

• Do not share it in chat or screenshots

6. Create templates

Before your app can send mail, create templates in the dashboard.

1. Open Templates
2. Choose the project you just created
3. Click Create template
4. Set the Name to the exact value your app will send (for example password_reset)
5. Write the subject and body
6. Use placeholders that match the keys in your JSON data

Copy the full subject and body examples from Example templates below. A short password_reset body looks like this:

Hello {{user_name}},

An administrator has reset your password.

Your new temporary password: {{password}}

If your request sends:

{
  "data": {
    "user_name": "Jane",
    "email": "user@example.com",
    "password": "TempPass123"
  }
}

then the template must use those exact names.

Template names are case-sensitive. password_reset is not the same as Password_Reset.

7. Test with curl

Test from your terminal before writing application code.

export NEXUS_API_KEY="your-secret-key"
export NEXUS_BASE_URL="https://nexuszm.com/api/v1"

curl -X POST "${NEXUS_BASE_URL}/notifications" \
  -H "Authorization: Bearer ${NEXUS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "password_reset",
    "to": "user@example.com",
    "data": {
      "user_name": "Jane",
      "email": "user@example.com",
      "password": "TempPass123"
    }
  }'

A successful response looks like:

{
  "id": 12,
  "request_id": "abc123xyz",
  "status": "queued",
  "message": "Notification queued for delivery"
}

HTTP 202 means Nexus accepted the request. Then check Delivery logs in the dashboard, or poll the status endpoint below.

10. Example templates

These examples show common templates. For each one, copy the name, subject, and body into Templates in the dashboard. Then send the same template name and data keys from your backend.

The HTTP contract stays the same for any other notification you add later — only the name and placeholders change.

15. Common mistakes

Wrong template name

The name in JSON must match the dashboard exactly. If it does not, the request may still return 202, then fail later with Template not found.

"template": "password_reset"   yes
"template": "Password Reset"   no
"template": "PASSWORD_RESET"   no

Template not found

Create the template under the same project whose API key you are using. A template on another project will not match.

Placeholder mismatch

If the template uses {{user_name}} but your payload sends username, that field stays blank. Match the keys exactly.

Missing or invalid API key

A missing or wrong key returns 401 with Invalid or missing API key. Regenerate the key in the project page and update your environment variables.

Wrong URL

A wrong base URL returns 404. The send path is:

https://nexuszm.com/api/v1/notifications

17. Common errors

Nexus returns errors in two places:

1. Immediately on the HTTP response when the request is rejected
2. Later in delivery status when the request was accepted (202) but sending failed

Always check both the HTTP response and Delivery logs (or GET /notifications/{request_id}).

HTTP errors (request rejected)

Example error body:

{
  "error": "Invalid or missing API key"
}

Delivery errors (after HTTP 202)

A 202 response means Nexus queued the notification. It can still fail while rendering or sending.

Example status response after a failed send:

{
  "id": 42,
  "status": "failed",
  "error_message": "Template not found",
  "template": "password_reset"
}

Quick checks when something fails

• Confirm the Authorization header is Bearer <api_key>

• Confirm the template name matches the dashboard exactly

• Confirm the template belongs to the same project as the API key

• Confirm to is a valid email string

• Open Delivery logs in the dashboard

18. FAQ

Can I call Nexus from the browser or a mobile app?
No. The API key would be exposed. Always call Nexus from your backend.

Are template names case-sensitive?
Yes. Use the exact name from the dashboard.

Must all data values be strings?
Yes for best compatibility. Send "15" instead of 15.

What does HTTP 202 mean?
Nexus queued the email. It can still fail later (for example Template not found). Check delivery with GET /notifications/{request_id} or in Delivery logs.

Do I need a separate API key per environment?
Yes. Create one project for staging and another for production.

Does Nexus support attachments?
This API uses template + data only. Check with your Nexus admin for extra features.