VRTex API Documentation

The VRTex REST API lets you send transactional email programmatically. Every endpoint is authenticated with your API key. This guide covers authentication, sending, domains, SMTP, templates, webhooks and events.

Base URL

https://api.vrtex.in/v1

Introduction

The VRTex API accepts JSON requests and returns JSON responses. All timestamps are ISO 8601 strings. IDs are prefixed strings such as email_....

When an email is accepted it is queued and the API returns 202 Accepted. Delivery happens asynchronously through our worker. You can track the result through the log endpoints or webhooks.

Authentication

Authenticate every request with the header Authorization: Bearer and your API key. Create keys in the dashboard under API Keys.

authenticate.sh

curl -X POST https://api.vrtex.in/v1/emails \
  -H "Authorization: Bearer re_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Security note: API keys are shown only once when created. Store them somewhere safe such as a secret manager or environment variable — never in client-side code or committed to source control.

Send an email

The core endpoint. It accepts an email with one or more recipients and queues it for delivery. The from address must use a domain you have added and verified.

POST/v1/emails

Sends an email and returns 202 Accepted once queued.

send-email.sh

curl -X POST https://api.vrtex.in/v1/emails \
  -H "Authorization: Bearer re_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourcompany.com",
    "fromName": "VRTex",
    "to": ["user@example.com"],
    "subject": "Welcome to VRTex!",
    "html": "<h1>Welcome aboard</h1><p>Thanks for joining.</p>",
    "text": "Welcome aboard! Thanks for joining.",
    "replyTo": "support@yourcompany.com",
    "tags": ["welcome", "signup"],
    "metadata": { "user_id": "12345" }
  }'

send-email.js

const res = await fetch("https://api.vrtex.in/v1/emails", {
  method: "POST",
  headers: {
    Authorization: "Bearer re_xxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "hello@yourcompany.com",
    to: ["user@example.com"],
    subject: "Welcome to VRTex!",
    html: "<h1>Welcome aboard</h1><p>Thanks for joining.</p>",
  }),
});

// 202 Accepted
// {
//   "id": "email_9f2h3k",
//   "status": "queued"
// }

Request fields

Field	Type	Required	Description
from	string	yes	Verified sender email address
fromName	string	no	Display name of the sender
to	string[]	yes	Recipient email addresses (max 100)
cc	string[]	no	Carbon copy recipients
bcc	string[]	no	Blind carbon copy recipients
replyTo	string	no	Reply-to address
subject	string	yes	Email subject line
html	string	yes*	HTML body (html or text required)
text	string	no	Plain text fallback
attachments	object[]	no	Attachments (filename, content)
headers	object	no	Custom message headers
tags	string[]	no	Tags for filtering logs
metadata	object	no	Arbitrary key/value metadata
scheduledAt	ISO 8601	no	Send at a future time
idempotencyKey	string	no	Prevents duplicate sends

Send a batch

Send up to 100 emails in one request. Each message is validated and submitted independently.

POST/v1/batch

Takes a messages array of the same shape as a single email.

send-batch.js

const res = await fetch("https://api.vrtex.in/v1/batch", {
  method: "POST",
  headers: {
    Authorization: "Bearer re_xxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [
      { from: "noreply@yourcompany.com", to: ["a@example.com"], subject: "Hey A", html: "<p>Hi</p>" },
      { from: "noreply@yourcompany.com", to: ["b@example.com"], subject: "Hey B", html: "<p>Hi</p>" },
    ],
  }),
});

Add a domain

You can only send from domains you own. Add a domain and verify it before sending. To use hello@yourcompany.com, add yourcompany.com.

POST/v1/domains

Body: { "name": "yourcompany.com" }

GET/v1/domains

Lists all your domains and their verification status.

GET/v1/domains/:id/dns

Returns the exact DNS records you need to add.

POST/v1/domains/:id/verify

Re-checks DNS and returns the updated verification status.

DELETE/v1/domains/:id

Removes the domain. Emails from it will be rejected.

DNS Records

When you add a domain, VRTex generates a DKIM key pair and tells you the DNS records to publish at your DNS provider:

Type	Name	Purpose
TXT	@	SPF — authorizes VRTex servers
TXT	vrtex._domainkey	DKIM — public signing key
TXT	_dmarc	DMARC — reporting policy
MX	@	MX — for bounce handling

Copy the exact values from GET /v1/domains/:id/dns. DNS changes can take a few minutes to propagate. Click verify once the records live.

Verify a domain

After publishing the DNS records, trigger verification:

verify-domain.sh

curl -X POST https://api.vrtex.in/v1/domains/:id/verify \
  -H "Authorization: Bearer re_xxxxxxxxxxxxxxxxxxxx"

Verification checks SPF, DKIM and DMARC records in real DNS and updates the domain status. Sending is only allowed once the domain is VERIFIED.

SMTP

Existing applications that speak SMTP can send through VRTex using their API key credentials:

smtp-settings

Host:     smtp.vrtex.in
Port:     587
Security: STARTTLS
Username: your_api_key
Password: your_api_secret

# Alternative: TLS on port 465

Setting	Value
Host	smtp.vrtex.in
Port	587
Encryption	STARTTLS
Username	your_api_key
Password	your_api_secret (shown once on key creation)

Templates

Templates store a subject and body once, so you can send with variables instead of hand-writing HTML every time. Variables use {{double.braces}}.

POST/v1/templates

GET/v1/templates

GET/v1/templates/:id

PUT/v1/templates/:id

DELETE/v1/templates/:id

POST/v1/templates/:id/preview

Renders the template with a variables object and returns subject, html and text.

template-preview.sh

curl -X POST https://api.vrtex.in/v1/templates/:id/preview \
  -H "Authorization: Bearer re_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": { "user.name": "Ada", "company.name": "Acme" }
  }'

Webhooks

Webhooks notify your server in real time when email events occur. VRTex POSTs a JSON payload to your endpoint and retries with exponential backoff until delivery succeeds.

POST/v1/webhooks

GET/v1/webhooks

PUT/v1/webhooks/:id

DELETE/v1/webhooks/:id

GET/v1/webhooks/:id/deliveries

webhook-payload.json

{
  "type": "email.delivered",
  "id": "evt_3x8k2m1",
  "email_id": "email_9f2h3k",
  "timestamp": 1786543210,
  "data": {
    "subject": "Welcome to VRTex!",
    "from": "hello@yourcompany.com",
    "to": ["user@example.com"]
  }
}

Email events

Every email goes through a lifecycle. Its status reflects the latest event:

Event	Description	Webhook
queued	Accepted and waiting in the queue	`email.sent`
sending	Worker picked it up	`email.sent`
sent	Accepted by the relay	`email.sent`
delivered	Landed in recipient inbox	`email.delivered`
opened	Recipient opened it	`email.opened`
clicked	Recipient clicked a link	`email.clicked`
bounced	Permanently rejected	`email.bounced`
failed	Permanently failed after retries	`email.failed`
complained	Recipient marked as spam	`email.complained`

Errors

Errors return a JSON object with statusCode and message.

error.json

{
  "statusCode": 400,
  "message": "Domain example.com is not verified. Complete DNS verification first."
}

Code	Meaning
400	Invalid request — validation failed or unverified sender
401	Missing or invalid API key
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Get started free Back to top