API Documentation

Send a transactional email with a single POST. All fields, defaults, and rules are below.

Endpoint

POST https://notifyvia.email/api/v1/send

Required headers

X-Api-Key — your host API key
Content-Type — application/json

Request body

Either html or text must be provided.

Field	Type	Required	Default	Description
to	email	yes	—	Recipient email address.
subject	string	yes	—	Email subject line.
html	string	conditional	—	HTML body. Required if `text` is not provided.
text	string	conditional	—	Plain text body. Required if `html` is not provided.
enable_spam_checker	boolean	no	`false`	Scan the body against the spam dictionary and reject if matched.
enable_rate_limiter	boolean	no	`false`	Enforce a per-host rate limit for this request.
limit	integer	no	`3`	Max requests are allowed within the window (when the limiter is on).
within_seconds	integer	no	`300`	Rate limiter window length in seconds.
ipv4_address	IPv4	conditional	`null`	Sender IP. Required when `enable_rate_limiter` is `true` (this would commonly be the website visitor's IP).
service	string	no	`"zepto"`	Provider to route through. One of: `"zepto"`, `"postmark"`.

Example

r POST https://notifyvia.email/api/v1/send

curl -X POST https://notifyvia.email/api/v1/send \
  -H "X-Api-Key: 1.sdf548..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "A message from your website",
    "text": "Do you have any strawberry cheesecake?\nOr maybe vanilla?",
    "enable_spam_checker": true,
    "enable_rate_limiter": true,
    "limit": 3,
    "within_seconds": 300,
    "ipv4_address": "203.0.113.10",
    "service": "zepto"
    }'

Responses

Every response is JSON with the shape { "message": string, "data": any | null, "errors": array | null }.

Status	Message	When
200	"Email Provisioning"	The request passed validation, rate limiting, and spam checks. The message has been queued for delivery through the selected provider.
401	"Authorization required"	Missing or invalid `X-Api-Key` header.
422	"Invalid"	Schema validation failed. `errors` contains the per-field messages from the validator.
422	"Invalid account"	The API key was accepted but no matching account was found.
422	"Insufficient credits"	The account's balance would go negative after this send and unlimited credits is not enabled.
422	"IPv4 address not provided for rate limiter"	`enable_rate_limiter` was `true` but `ipv4_address` was omitted.
422	"Spam detected"	The body matched an entry in the spam dictionary. A `SPAM_BLOCKED` usage record is logged.
422	"Invalid service"	The `service` value was not one of the supported providers.
429	"Rate limit exceeded"	More than `limit` requests within `within_seconds` for the given IP address.

Success example

{
  "message": "Email Provisioning",
  "data": null,
  "errors": null
}

Error example

{
  "message": "Invalid",
  "data": null,
  "errors": {
    "to": ["Not a valid email address."]
  }
}