Email API

Send emails programmatically using the Voxvaani Email API.

Base URL


https://voxvaani.com/api/v1

Authentication

All requests require an API key in the header: x-api-key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY

Required scope: email:send

⚠️ SMTP Configuration Required

Before using the Email API, your SMTP server must be configured in Settings . The Email API routes messages through your configured SMTP provider. Without valid SMTP credentials, all email API requests will fail.

Verify your SMTP setup by sending a test email through the dashboard interface before integrating with the API.

Send Email

Send an email to one or more recipients.

Endpoint: POST /email/send

Request Body (JSON)

Parameter	Type	Required	Description
`to`	string	Yes	Recipient email address, or comma-separated list for multiple recipients
`subject`	string	Yes	Email subject line
`html`	string	One of	HTML body content. Required unless `text` is supplied.
`text`	string	One of	Plain-text body. Required unless `html` is supplied. Used as the message body when `html` is omitted.
`fromName`	string	No	Display name for the sender (e.g., “Voxvaani Support”). Uses organization default if omitted.
`replyTo`	string	No	Reply-to address. Defaults to your configured SMTP sender when omitted.
`important`	boolean	No	Marks the message as high priority

Success Response


{
  "success": true,
  "messageId": "uuid-string",
  "cost": 0,
  "remainingBalance": 50000
}

Error Response

Errors return an error field with a descriptive message:


{
  "error": "Parameters to, subject, and either html or text are required"
}

Status	Cause
`400`	`to`, `subject`, or both body fields are missing
`400`	SMTP is not configured on your account
`402`	Insufficient email balance
`500`	The SMTP provider rejected the message

Examples

HTML Email


curl -X POST "https://voxvaani.com/api/v1/email/send" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Welcome to Our Service",
    "html": "<h1>Welcome!</h1><p>Thank you for signing up. Your account is ready.</p><p><a href=\"https://example.com/dashboard\">Go to Dashboard</a></p>"
  }'

Plain Text Email


curl -X POST "https://voxvaani.com/api/v1/email/send" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Account Update",
    "text": "Your account has been updated successfully.\n\nLogin at: https://example.com/login\n\nRegards,\nVoxvaani Team"
  }'

With Sender Name


curl -X POST "https://voxvaani.com/api/v1/email/send" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Project Update - July 2026",
    "html": "<h2>Project Status</h2><p>The project is on track for the August 1 deadline.</p>",
    "fromName": "Project Team"
  }'

Send to Multiple Recipients


curl -X POST "https://voxvaani.com/api/v1/email/send" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected],[email protected],[email protected]",
    "subject": "Team Announcement",
    "html": "<p>Hello team, please review the updated policy document attached to the company portal.</p>"
  }'

Email Balance

Email sending is deducted from your account’s email balance. One email credit is consumed per recipient. For example, sending to 3 recipients consumes 3 email credits.

Ensure you have sufficient credits before sending. Check your balance via:


curl -X GET "https://voxvaani.com/api/v1/balance" \
  -H "x-api-key: YOUR_API_KEY"

Look for the emailBalance field in the response.

Tips

Use HTML for formatted emails with links, images, and styled text
For plain text transactional emails, use the text field
Ensure your SMTP is configured in Settings before sending
Monitor your email balance to avoid failed sends — each recipient consumes one credit
Set a fromName for a professional sender display name in the recipient’s inbox
Test your SMTP configuration by sending a single email before bulk operations
For high-volume sending (1,000+ emails), stagger your API calls or use the bulk email campaign feature in the dashboard