Senders

Sender identities represent the "from" addresses used when sending email. Each sender must be verified before it can be used to send messages.

Create a sender

POST /api/senders
{
  "name": "Marketing",
  "fromEmail": "marketing@yourdomain.com",
  "fromName": "Marketing Team",
  "replyToEmail": "reply@yourdomain.com",
  "provider": "sendgrid",
  "priority": 0,
  "isDefault": true
}

Sender fields

Field	Type	Required	Description
`name`	string	Yes	Sender identity name
`fromEmail`	string	Yes	From email address
`fromName`	string	No	Display name shown to recipients
`replyToEmail`	string	No	Reply-to email address
`provider`	string	No	Associated provider name
`priority`	number	No	Priority for automatic selection (lower = higher priority)
`isDefault`	boolean	No	Whether this is the default sender

Verification

When you create a sender, NevarMail initiates a verification process through the associated email provider. The sender's verificationStatus field tracks progress:

Status	Description
`pending`	Verification initiated, waiting for confirmation
`verified`	Sender is verified and ready to use
`failed`	Verification failed

Only verified senders can be used to send email.

List senders

GET /api/senders

Returns all sender identities with their verification status.

Update a sender

PUT /api/senders/:id
{
  "fromName": "Updated Marketing Team",
  "priority": 1
}

All fields are optional. Only provided fields are updated.

Delete a sender

DELETE /api/senders/:id

Returns { "deleted": true } on success.

Automatic sender selection

NevarMail can automatically select the best sender for each email based on configurable strategies.

POST /api/senders/select
{
  "recipientDomain": "example.com",
  "strategy": "priority"
}

Selection strategies

Strategy	Description
`priority`	Select the sender with the lowest priority number
`round-robin`	Rotate between available senders
(default)	Prefer the sender marked as `isDefault`

Response

{
  "sender": {
    "id": "...",
    "name": "Marketing",
    "fromEmail": "marketing@yourdomain.com"
  },
  "strategy": "priority",
  "reason": "Selected highest priority sender for example.com"
}

If no suitable sender is found, sender will be null.

Senders

On this page