Send an email

POSThttps://api.torvathmail.com/v1/emails

Send subject with html, text or both, or a stored template with its variables. The email is queued and sent within seconds; follow it with Get an email or its events.

Headers

Idempotency-Keystringoptional
8 to 64 letters, digits, - or _. Sending again with the same key (from the same API key) returns the first result and sends nothing more.

Body

fromstring or objectrequired
Any address on one of your verified domains.
Fields inside from
- emailstringrequired
- namestringoptional
tostring or array of stringsrequiredup to 50
ccstring or array of stringsoptionalup to 50
bccstring or array of stringsoptionalup to 50
replyTostringoptional
subjectstringoptional1 to 998 characters
htmlstringoptional
textstringoptional
Made from the HTML when left out. Send html, text or both.
attachmentsarray of objectsoptionalup to 20
Fields inside attachments
- filenamestringrequired
- contentstringrequired
  Base64
- contentTypestringoptional
tagsarray of stringsoptionalup to 10
metadataobjectoptionalstring values
Up to 20 keys; returned with every event.
trackobjectoptional
Business plan. Off unless asked for. Opens use an invisible image and clicks go through Torvath; machine events (Apple Mail's privacy proxy, link scanners) are marked.
Fields inside track
- opensbooleanoptional
- clicksbooleanoptional
templatestringoptional
Business plan. A stored template's name (made under API in Torvath), in place of subject, html and text.
variablesobjectoptionalstring, number or boolean values
Values for the template's {{name}} variables; every one is needed. Escaped in the HTML.

Response

idstringrequired
recipientsintegerrequired

Status codes

200
Already sent with this Idempotency-Key
201
Queued for sending
400
The request isn't valid. field names the part to fix.bad_requestsuppressedmissing_variables
401
No API key, or it isn't valid or was revoked.unauthorized
403
The key or plan doesn't allow this.forbiddenapi_offneeds_business
404
Nothing with that id or name.not_foundtemplate_not_found
409
Your organisation's settings or state stop it.events_offdomain_blockedstorage_fullorg_inactive
429
A limit is reached. Wait, or raise the limit.rate_limiteddaily_limitmonthly_limitspending_limit
503
Sending is briefly unavailable. Try again shortly.no_providersend_busy

Refusals share one shape. See errors.

Templates

On the Business plan, make templates under Admin → API → Templates, with {{name}} where a detail goes. Send one by name in place of subject, html and text. Every variable needs a value, or the email is refused with missing_variables, so a half-filled email never goes out. Values are made safe in the HTML.

Body

{
  "from": "billing@yourcompany.in",
  "to": "asha@example.com",
  "template": "invoice-ready",
  "variables": { "name": "Asha", "amount": "₹500" }
}

Open and click tracking

On the Business plan, ask for it per email with "track": { "opens": true, "clicks": true }. It is off unless you ask, and only for emails to one recipient. Links with data-no-track are left alone.

Good to know

Every address in to, cc and bcc counts as one recipient towards your allowance.
An address that bounced or reported spam before is refused with suppressed. Remove it under Admin → API to send to it again.
metadata and tags come back with every event, so you can tie events to your own records.