Torvath Keys, errors and limits
How requests are signed in, what a refusal looks like, and the limits that apply to every organisation.
API keys
Every request carries an API key in the Authorization header. Admins make keys under Admin → API. A key is shown once, when it is made; if it is lost, make a new one and revoke the old.
curl https://api.torvathmail.com/v1/emails/em_7Kq2xY9pLm3nB8vR \
-H "Authorization: Bearer $TORVATH_API_KEY"Each key can be limited to what one app needs:
- Send email and Take events: what the key may do. A key without one of them is refused with
forbidden. - Send from: any of your domains, or only the ones you pick.
- Test key: starts
tv_test_, checks everything and sends nothing. See Testing.
Errors
A refused request answers with a 4xx or 5xx status and the same JSON shape every time. error is a code that stays the same, for your code to check. message is for a person to read and may change. field names the part of the request to fix, when there is one.
{
"error": "suppressed",
"message": "Mail can't be delivered to old@example.com. Earlier mail bounced or was reported as spam. Remove it to send.",
"field": "to"
}| Status | Meaning |
|---|---|
400 | The request isn't valid. field names the part to fix. |
401 | No API key, or it isn't valid or was revoked. |
403 | The key or plan doesn't allow this. |
404 | Nothing with that id or name. |
409 | Your organisation's settings or state stop it. |
429 | A limit is reached. Wait, or raise the limit. |
503 | Sending is briefly unavailable. Try again shortly. |
Error codes
| error | Why |
|---|---|
bad_request | A field is missing or not valid. field names it. |
suppressed | Earlier mail to an address bounced or was reported as spam. Remove it under API in Torvath to send to it again. |
missing_variables | A template variable has no value. missing lists them. |
unauthorized | No key, or the key isn't valid or was revoked. |
forbidden | The key can't do this: it can't send, can't take events, or can't send from that domain. |
api_off | The email API isn't turned on for your organisation. |
needs_business | Templates, and open and click tracking, are part of the Business plan. |
not_found | No email with this id. Emails are kept 30 days (90 on Business). |
template_not_found | No template with that name. |
events_off | Events aren't turned on. An admin turns them on under API in Torvath. |
domain_blocked | The from domain isn't verified, or sending from it is paused. |
storage_full | Your organisation's storage is full. |
rate_limited | More than 300 requests in a minute with this key. |
daily_limit | A new organisation's daily limit for its first 2 weeks. |
monthly_limit | This month's API allowance is used up. It resets on the 1st. |
spending_limit | Pay as you go has reached its monthly spending limit. |
no_provider, send_busy | Sending is briefly unavailable. Try again shortly. |
Retries and idempotency
Try again after 429 rate_limited, any 5xx, or a lost connection, waiting a little longer each time. Don't retry other 4xx answers: the same request will be refused again.
To make a retried send safe, give it an Idempotency-Key header, such as your invoice number. Sending again with the same key returns the first result with status 200 and sends nothing more. The Node SDK does this for you.
Limits
| Limit | Value |
|---|---|
| Requests per key | 300 a minute |
| Recipients per email (to, cc and bcc together) | Up to 50 in each of to, cc and bcc |
| Attachments | Up to 20 per email, within your plan's attachment size |
| Tags | Up to 10, each 1 to 64 letters, digits, ., - or _ |
| Metadata | Up to 20 keys, values up to 256 characters |
| New organisations | 100 recipients a day for the first 2 weeks |
| Emails kept for Get an email | 30 days, 90 on Business |
| Events kept until acknowledged | 7 days, 30 on Business |
Each plan includes API emails every month, counted by recipient. See pricing for the allowance and pay as you go.