Sending Email

Send plain emails, templated emails, and scheduled emails through the NevarMail API.

NevarMail provides three ways to send email: direct sends, templated sends with variable substitution, and scheduled sends for future delivery.

Send a plain email

Send a single email with a subject, body, and recipient.

POST /api/email/send
{
  "to": "recipient@example.com",
  "subject": "Order Confirmation",
  "html": "<h1>Order Confirmed</h1><p>Your order #1234 has been placed.</p>",
  "text": "Order Confirmed. Your order #1234 has been placed."
}

Request fields

Field	Type	Required	Description
`to`	string	Yes	Recipient email address
`cc`	string	No	CC email address
`bcc`	string	No	BCC email address
`subject`	string	Yes	Email subject line
`html`	string	No	HTML body content
`text`	string	No	Plain text body content
`templateId`	string	No	Template ID to associate with this send
`provider`	string	No	Provider to use (defaults to auto-selection)
`priority`	string	No	`"low"`, `"normal"` (default), or `"high"`
`metadata`	object	No	Arbitrary metadata to attach

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "messageId": "msg-abc123@yourdomain.com",
  "status": "sent",
  "provider": "sendgrid",
  "sentAt": "2026-03-22T12:00:00.000Z"
}

Send a templated email

Send emails using a pre-built template with variable substitution. This is ideal for transactional emails like welcome messages, order confirmations, and password resets.

POST /api/email/send-templated
{
  "templateId": "tmpl-welcome-001",
  "variables": {
    "user": {
      "name": "Jane Smith"
    },
    "company": {
      "name": "Acme Inc"
    }
  },
  "recipients": [
    "jane@example.com"
  ]
}

Request fields

Field	Type	Required	Description
`templateId`	string	Yes	The template to use
`variables`	object	Yes	Variables to interpolate into the template
`recipients`	string[]	Yes	Array of recipient email addresses

The response returns one result per recipient.

See Templates for creating and managing templates.

Schedule an email

Schedule an email for future delivery. Scheduled emails support automatic retries if the initial send fails.

POST /api/email/schedule
{
  "to": "recipient@example.com",
  "subject": "Weekly Report",
  "html": "<h1>Your weekly report is ready</h1>",
  "scheduledFor": "2026-03-25T09:00:00.000Z"
}

The request body includes all the same fields as a plain email send, plus:

Field	Type	Required	Description
`scheduledFor`	string	Yes	ISO 8601 datetime for when to send

List scheduled emails

GET /api/email/schedule

Returns all scheduled emails with their current status:

[
  {
    "id": "...",
    "emailData": { "to": "...", "subject": "..." },
    "scheduledFor": "2026-03-25T09:00:00.000Z",
    "status": "scheduled",
    "retryCount": 0,
    "maxRetries": 3
  }
]

Cancel a scheduled email

DELETE /api/email/schedule/:id

Returns { "cancelled": true } on success. Only emails with status "scheduled" can be cancelled.

Provider selection

When you do not specify a provider in the request, NevarMail automatically selects the best available provider based on:

Health status -- Unhealthy providers are skipped
Rate limits -- Providers at capacity are deprioritized
Priority -- Lower priority number means higher preference

You can override this by passing a provider field in your send request.

Sending Email

On this page