Sending email

Notavia sends transactional email two ways. Pick per environment in Settings → Email.

Managed sending (zero setup)

The fastest start: Notavia sends through its managed provider (Amazon SES). You add your sender domain, Notavia gives you DNS records (DKIM), and once they verify you can send live. No provider account of your own required.

Per-message sender identity

Every environment has a default sender identity (Settings → Providers). Individual sends can override all three parts of it — the From address, the From display name, and the reply-to — which is what lets one application send on behalf of many of its own customers.

POST /v1/notifications
{
  "channel": "email",
  "recipient": { "address": "user@example.com", "name": "Ada" },
  "subject": "Reset your password",
  "html_body": "<p>…</p>",
  "from_name": "Acme Support",
  "from_address": "noreply@acme.com",
  "reply_to": "support@acme.com"
}

The recipient sees From: Acme Support <noreply@acme.com> and replies go to support@acme.com. Omit a field and the environment’s default fills it in.

You may only send From a domain you have proven you control

from_address must name a verified sender domain for your organization — see Sender domains — or be your environment’s own configured From address. Anything else is a 403 with code from_address_not_verified, and no mail is sent — not even a notification record is created. There is no silent fallback to the environment default: sending from an identity you did not ask for is worse than an error you can see.

This is the same error the environment-level go-live check returns, because it is the same rule — you may only send From a domain you have proven you control — applied to one message instead of the whole environment. The error message names the offending address, so you can tell the two apart.

This applies in test environments too. There is no reason to let a test send claim a domain you have not proven, and a rule that only bites in production is a rule you discover at the worst moment.

Verify acme.com and you may send from @acme.com — you own it. Nothing lets you send from @some-bank.com, because you cannot publish _notify-verification.some-bank.com.

Field rules

from_address is a bare address — noreply@acme.com, never Acme Support <noreply@acme.com>; the display name belongs in from_name. It is capped at 320 characters. reply_to follows the same bare-address rule and cap. from_name may not contain <, >, or control characters and is capped at 200 characters. All three are email-channel only — sending one on another channel is a validation error, not a silent drop.

All three participate in idempotency: two sends sharing an Idempotency-Key but differing in any of them are a 409 conflict, not a replay. A key is a promise that the same message is being retried, and a different sender is a different message.

Managed sending with a locked sender

If your environment uses managed sending with an operator-locked sender, per-message from_address and from_name are both ignored and a warning is logged — a locked sender pins the whole identity to protect the shared sending domain’s reputation. Use a bring-your-own provider, or an unlocked managed sender, to send a per-message identity.

Bring your own provider

Already have SendGrid, Resend, Postmark, Mailgun, Azure Communication Services, or any SMTP host? Add it in Settings → Providers and Notavia relays through it — your provider, your reputation.

Failover between providers

Add more than one provider and order them. Notavia tries them in order on every send: if the first rejects the message with a provider fault — a revoked key, a rate limit, a 5xx — it moves to the next one immediately, within the same send. A message is only failed once every provider in the chain has refused it.

Failures that are the message’s fault (an invalid recipient, rejected content) stop the chain instead of failing over. Retrying a bad address on a second provider would just burn your reputation twice.

Provider health and alerts

Deliverability (Pro and above) shows each provider separately: how many messages it attempted, how many it sent, how many it dead-ended, and how many it handed off to the next provider in your chain. A blended bounce rate across providers tells you something is wrong; this tells you which one.

You do not have to watch it. When a provider starts failing your sends, Notavia will:

• email every owner and admin — sent over Notavia’s own infrastructure, never through the provider that is broken;
• POST a provider.critical webhook you can wire to your pager;
• show a banner on the Deliverability page.

You get a provider.recovered when it is genuinely delivering again — which means it has actually sent mail, not merely gone quiet. Test environments do not alert by default (you break things there on purpose); flip the switch on the Deliverability page if you want them to.

When one fires, this runbook walks you through what it means, how to fix it, and why it will not clear the moment you think it should.

Sender domains & white-label

Email is sent from your domain, not Notavia’s. Verify the domain (Settings → Domains) to unlock live sending, and set per-tenant branding so the message — and any hosted unsubscribe pages — look like your product.

Everything on this page is available programmatically: POST /v1/sender-domains registers a domain and returns the DNS records to publish, GET /v1/sender-domains/{id} is the poll that tells you when it verified, and POST /v1/sender-domains/{id}/recheck forces a check now. The organization and environment come from your API key. That is what lets a platform provision sending domains for its own customers without a human in the loop — register the domain, relay the DNS records to your customer, poll until verified, then send with that domain in from_address.

Domain authentication (SPF, DKIM, DMARC)

Mailbox providers decide whether to trust your mail from three DNS records. When you add a sender domain, Notavia runs a live Email authentication checklist (Settings → Domains, expand a domain) and, where a record is missing or weak, hands you the exact value to publish:

• DKIM cryptographically signs every message. For managed sending Notavia gives you the DKIM records; together with domain ownership, this is what gates live sending.
• SPF authorizes the hosts allowed to send for your domain. Advisory — a warning never blocks sending, but publishing a correct record is best practice.
• DMARC tells mailbox providers what to do with mail that fails authentication and stops others spoofing your domain. Advisory, but now effectively required by Gmail and Yahoo for bulk senders — start with p=none to monitor, then tighten to quarantine or reject.

Each check reads Pass, Warn, or Fail and refreshes on every recheck, so you can publish a record and confirm it live. SPF and DMARC stay advisory: they guide deliverability without holding up your first send.

Suppression

Bounces and complaints are ingested automatically and added to a suppression list so you never re-send to a known-bad address. See Suppressions & delivery feedback.