API Documentation

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

Endpoint

POST https://notifyvia.email/api/v3/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.
reply_to v2 Only email no - The email address that will be used if the recipient clicks reply.
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).
enable_cap v3 Only boolean no false Enable the captcha service, this is only compatible with the self-hosted service trycap.dev
cap_api_endpoint v3 Only string conditional - The site verify url of your instance, for example: https://{instance_url}/{site_key}/siteverify
cap_secret_key v3 Only string conditional - The secret key given after adding a website on your Cap instance.
cap_token v3 Only string conditional - The token from the HTML form at the frontend.
service string no "zepto" Provider to route through. One of: "zepto", "postmark".

Cap (captcha) Service Notes

When using this service either turn off "Restrict allowed origins" (aka CORS) or add notifyvia.email to the list.

Example

r POST https://notifyvia.email/api/v3/send 
curl -X POST https://notifyvia.email/api/v3/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",
    "enable_cap": true,
    "cap_api_endpoint": "https://cap.tasty-cheesecakes.com/0000000/siteverify",
    "cap_secret_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "cap_token": "xxxxxx",
    "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.
460 "Invalid" Schema validation failed. errors contains the per-field messages from the validator.
461 "Invalid account" The API key was accepted but no matching account was found.
462 "Invalid service" The service value was not one of the supported providers.
463 "Insufficient credits" The account's balance would go negative after this send and unlimited credits is not enabled.
464 "IPv4 address not provided for rate limiter" enable_rate_limiter was true but ipv4_address was omitted.
465 "Spam detected" The body matched an entry in the spam dictionary. A SPAM_BLOCKED usage record is logged.
466 "Senders IPv4 address has been blocked" The sender's ipv4_address is on the global IP block list. A BANNED usage record is logged.
467 "Captcha verification failed" One of three things can be invalid: The token, the API URL or the secret key. Check the error response for more information.
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."]
  }
}