Set up a “from” address

Sender identities represent the "from" addresses used when sending email. A sender you create here is ready to use immediately -- what earns the right to send from an address is authenticating its domain, not a per-sender step.

POST /api/senders below requires a signed-in browser session -- API keys get a 403 SESSION_ONLY error. To create a sender with an API key, use POST /api/v1/senders instead (same fields, standard {data, requestId} v1 envelope).

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

Which sender a send uses

A send that names a from uses it. A send that names none uses, in order:

1. the use case's sender, set on the use case page (Sender card), when that sender is active;
2. otherwise the project's default sender, with its display name and reply-to;
3. otherwise nothing: the send is refused with 409 FROM_UNRESOLVABLE. A scheduled send is refused the same way when you schedule it, not when it fires. NevarMail never falls back to an address of its own.

A sender imported from your provider counts only once the provider has verified it; until then it is neither offered on the use case page nor used as a default.

Give each use case its own sender when its mail should come from a distinct address, for example login@auth.yourdomain.com for sign-in mail and news@yourdomain.com for a newsletter. Deleting or deactivating that sender puts the use case back on the project default.

Eligibility

NevarMail does not verify senders, and does not require you to. Authenticate the domain (see Domains) and every address on it can send.

One case is different: a sender imported from your provider, which carries a providerSenderId. There the isVerified field mirrors your provider's own answer, and NevarMail will not select an address the provider has said it will refuse -- on SendGrid, sending from such an address returns "The from address does not match a verified Sender Identity". In the app those rows are marked Not verified at provider.

Note that SendGrid treats any address on an authenticated domain as verified automatically, so this normally resolves itself the moment your domain is authenticated. It bites only for an address on a domain you have not authenticated, where SendGrid expects Single Sender Verification instead.

To clear the last case: verify the address in your provider account (or authenticate its domain), then re-sync. POST /api/v1/senders/import re-reads your provider account and updates rows whose answer has changed, reporting them in the refreshed count; in the app, use Re-sync from provider on the Senders page.

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.

This is a browser-session-only endpoint with no API equivalent -- it cannot be called with an API key, and there is no v1 equivalent of the select route.

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

Selection strategies

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.