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/scheduleReturns 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/:idReturns { "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.