Trovacast

Messaging

Email

Send transactional and marketing email from your own verified domain or SMTP account, with consent by category, suppressions and delivery events.

Email is a messaging channel like WhatsApp: the same POST /v1/messages with channel: "email", the same message resource and message.* events, the same idempotency. It sends through the project’s own email account — a sending domain verified into Trovacast’s Amazon SES account (claimable through this API), or the project’s own SMTP server, set up in the console. With neither, a send is 409 CHANNEL_NOT_CONFIGURED: Trovacast’s own mail never sends for you.

Sending domains

Claim a domain (email:manage) and publish the DNS records it answers with — three DKIM CNAMEs, the MAIL FROM MX and SPF, and an advisory DMARC. A subdomain is recommended: it keeps sending reputation apart from your people’s own mail. Each record’s verdict is what Trovacast’s resolver last saw (ok, missing, mismatch, unchecked), so you can tell which record is wrong.

Claim a sending domain
curl -X POST 'https://api.trovacast.com/v1/email/domains' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: claim-mail-acme-com' \
  -H 'Content-Type: application/json' \
  -d '{
  "domain": "mail.acme.com"
}'
  • POST /v1/email/domains/{domain}/verify re-checks now (unverified domains are also re-checked every few minutes). Only status: verified sends: Amazon SES must verify it and Trovacast’s resolver must see its DKIM records.
  • A verified domain is re-checked daily. If SES stops verifying it, or its DKIM records have been missing for 48 hours, it becomes temporary_failure (or failed) and sends through it are refused with EMAIL_DOMAIN_NOT_VERIFIED until it verifies again.
  • DELETE /v1/email/domains/{domain} releases it (with ?version=, only that version; 409 CONFLICT if it moved).
  • Limits: 10 domains per project by default (the platform can raise one project's cap; the refusal's limit says which applies), 3 not yet verified (409 EMAIL_DOMAIN_LIMIT, 409 EMAIL_DOMAIN_PENDING_LIMIT). An address, an IP, a public suffix or the platform’s own domain is a 400.

Send an email

Send a transactional email
curl -X POST 'https://api.trovacast.com/v1/messages' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: order-1001-confirmation-email' \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "email",
  "type": "text",
  "to": {
    "email": "aarav@example.com"
  },
  "text": "Your order #1001 is confirmed.",
  "email": {
    "subject": "Your order #1001 is confirmed",
    "html": "<h1>Thanks!</h1><p>Your order <b>#1001</b> is confirmed.</p>",
    "category": "transactional",
    "replyTo": "support@acme.com"
  },
  "metadata": {
    "orderId": "1001"
  }
}'
  • Recipient: exactly one of contactId or to: { email }. A send by address uses the project’s contact with that address or creates an email-only one, so it also needs contacts:write. A contact without an address is 422 RECIPIENT_EMAIL_REQUIRED. Every refusal once the recipient is known carries its contactId.
  • **type: "text":** email.subject (required; one line, up to 998 characters), text and/or email.html, and email.category (required). HTML (up to 256 KB) is sanitized before it is stored: layout, inline styles, class and <style> blocks stay; scripts, event handlers, forms, frames, javascript: and data: links and CSS that loads anything are removed, and images load over https only. Without text, a plain-text part is derived from the HTML.
  • **type: "template":** an email template and its variables. Values are HTML-escaped into the HTML, which is sanitized again, so a value can never add markup. email.subject overrides the template’s subject; text and email.html are not allowed.
  • From: the account’s default address unless email.from (with email.fromName) or an email senderId names another — under one of the project’s verified sending domains, or the SMTP account’s own address; 409 FROM_NOT_ALLOWED otherwise. email.replyTo sets where replies go.
  • Copies: email.cc and email.bcc — at most 20 together, transactional only (marketing with copies is a 400). Each copy is checked like the recipient: a suppressed address is 409 EMAIL_SUPPRESSED, one belonging to a contact who opted out is 409 CONSENT_OPTED_OUT.
  • Attachments: email.attachments: [{ filename, contentType?, content }], base64 — at most 10 files and 7 MB in all. PDF, PNG, JPEG, GIF, WebP, plain text, CSV, .ics and .docx/.xlsx/.pptx; the bytes must really be that type. Executables, archives, HTML/SVG and legacy Office files are refused. Files are kept encrypted only until the email is sent or fails, then deleted.

marketing needs the contact’s email marketing: opted_in (409 CONSENT_REQUIRED, or CONSENT_MARKETING_REQUIRED when they agreed to transactional email only) and always carries a visible unsubscribe footer and one-click List-Unsubscribe headers. transactional needs no opt-in but is refused by an opt-out (409 CONSENT_OPTED_OUT: updates: opted_out, an unsubscribe or a spam report) and keeps the List-Unsubscribe headers without the footer. A contact-level opt-out and the suppression list refuse either. A MARKETING template is always marketing.

What comes back

The send answers 202 with the message queued, carrying email: { subject, from, to, cc, bcc, attachments } — addresses masked. On an Amazon SES account delivery is reported as message.sent, then message.delivered or message.failed; an SMTP account reports message.sent and nothing further.

Amazon SES reportsMessageEvent
Deliverydeliveredmessage.delivered
Hard bouncefailed, SES_BOUNCE_PERMANENT; the address is suppressed for goodmessage.failed
Soft bounce (SES gave up retrying)failed, SES_BOUNCE_TRANSIENT; the address is suppressed for 7 daysmessage.failed
Held back by SES’s own account-wide listfailed, SES_ACCOUNT_SUPPRESSED; not added to your listmessage.failed
Complaint (reported as spam)Unchanged (it was delivered); the address is suppressed and the contact’s email consent opted outmessage.complained, contact.consent.updated
Reject or rendering failurefailed, SES_REJECT / SES_RENDERING_FAILUREmessage.failed

Billing: each email is rated at your plan’s email rate when the provider accepts it; a bounce or rejection reported afterwards refunds it. Exactly once: the Idempotency-Key replay works as for WhatsApp, but neither SES nor SMTP takes an idempotency key, so a submission whose answer was lost fails as SUBMISSION_UNKNOWN and may have been delivered. On an SES account it resolves itself when SES reports on the message (it turns sent); wait for that before re-sending.

Opens and clicks

Off until you turn it on for a sending domain: PATCH /v1/email/domains/{domain} with { "tracking": { "opens": true, "clicks": true } }. HTML mail from the domain then carries a tracking pixel and its links go through signed redirects (never the unsubscribe link; plain text is untouched). The first open fires email.opened, the first click on each link email.clicked, and the message reads email.tracking with the counts. Hits from machines — Apple Mail Privacy Protection's prefetch, mail security scanners, link checkers, anything within seconds of the send — are answered but never counted, so Apple Mail opens are not reported.

Replies

Replies to a verified sending domain (or a subdomain of it, such as reply.acme.com) arrive as message.received on the thread of the email they answer, with the subject, the text and what each attachment was (attachments themselves are not kept). Point the reply domain's MX at the receiving service the platform runs; the sender's address is masked on the message and kept on the contact.

Suppressions

Addresses the project does not email. SES bounces and complaints add them automatically, and you can add your own (email:manage). The list never returns an address — only a mask such as a•••@example.com; GET /v1/email/suppressions?email= looks one address up. A suppression only widens: a complaint outranks a hard bounce or a manual entry, which outrank a soft bounce, and soft_bounce lapses after 7 days.

Suppress an address
curl -X POST 'https://api.trovacast.com/v1/email/suppressions' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "aarav@example.com",
  "note": "Asked by phone to stop all email"
}'

The note is stored unencrypted — never put personal data in it. Removing a complaint needs ?force=true&reason=… (409 SUPPRESSION_FORCE_REQUIRED otherwise), and does not reopen the contact’s email consent.

Endpoints

Events

EventWhen it is sentKey scopes
message.sentThe provider accepted a message you sent. WhatsApp (Meta), Amazon SES or the SMTP relay, or the SMS vendor accepted an outbound message. message.status is sent.data: messagemessages:read
message.deliveredA message reached the contact. The provider reported the message delivered to the contact’s phone or mailbox (for SMS: the vendor’s delivery receipt).data: messagemessages:read
message.failedA message failed for good. message.failure carries { code, reason }. A scheduled message cancelled before it was sent fails with MESSAGE_CANCELED.data: messagemessages:read
message.complainedA recipient reported an email you sent as spam. The message’s status does not change (it was delivered); the address is suppressed and the contact’s email consent opted out, which its own contact.consent.updated reports.data: complaint, messagemessages:read

Errors

CodeStatusMeaning and what to do
BILLING_INSUFFICIENT_CREDIT402The prepaid wallet, after any included plan minutes, cannot cover the messages at your plan's rate — or a call's ceiling: its maxDurationSec in started minutes, beside what your live API calls already in flight can still run to (inFlightMinutes), each at its own rate.What to do: Top up the prepaid balance (POST /v1/balance/top-ups, or Add credit in Settings → Billing), then retry. When the refusal carries maxDurationSecAvailable, a call with a maxDurationSec up to it is placed now; without it no shorter call fits — retry once a call in progress ends. See Limits and billing.
BILLING_RATE_UNAVAILABLE503Your plan has no rate for this channel and mode (or message category) — a configuration gap on our side, not a debt.What to do: Retrying will not help until the plan prices it: contact us. GET /v1/pricing shows the rates your plan has.
BILLING_SUBSCRIPTION_CANCELED402The subscription was cancelled at a period end.What to do: A project administrator chooses a plan in Settings → Billing, which reactivates the subscription; then retry.
BILLING_SUBSCRIPTION_PAST_DUE402The monthly fee is unpaid: it left the wallet negative.What to do: Top up enough to bring the balance back to zero or above (POST /v1/balance/top-ups): the subscription reactivates by itself, then retry.
BILLING_SUBSCRIPTION_SUSPENDED402The subscription is blocked by the platform.What to do: Retrying will not help until the hold is lifted: contact us.
CHANNEL_NOT_CONFIGURED409The project has not set the channel up — email: no email account of its own (the platform’s mail never sends for it); SMS: no SMS settings or DLT entity id — or the deployment does not carry it. On a call, the provider is not a channel this deployment runs or the organization has set up. Also a message.failed code when the account was disconnected after the message was queued; nothing was sent.What to do: Set the channel up in Settings → Channels (WhatsApp, Email or SMS) — for a call in Settings → Calling, or leave provider out — then retry. A message that failed with this code was never sent: send it again once the account is connected.
CONTACT_BLOCKED409The contact is blocked, so nothing is sent to them.What to do: Do not retry: nothing reaches a blocked contact, on any channel.
CONTACT_OPTED_OUT409On a send, the contact opted out of all contact or asked not to be contacted — it outranks every channel's consent. On a call, they opted out of calls themselves.What to do: Do not retry, and do not reach them another way. If the contact asks to hear from you again, a project member changes their state in the console.
EMAIL_DOMAINS_UNAVAILABLE503Amazon SES is not available on this deployment, so sending domains cannot be managed.What to do: Retrying will not help: send through your own SMTP account (Settings → Channels → Email) instead, or contact us.
EMAIL_DOMAIN_ALREADY_ADDED409This project has already claimed the domain.What to do: Use the domain you have (GET /v1/email/domains/{domain}): publish its records and re-check it instead of adding it again.
EMAIL_DOMAIN_CLAIMED409Another project holds the domain. The body carries a challenge TXT record.What to do: Publish the challenge TXT record and claim the domain again (POST /v1/email/domains): a holder that has not verified it gives way at once, and a never-verified claim lapses 72 hours after it was first made. A verified holder never gives way — contact us.
EMAIL_DOMAIN_LIMIT409The project already holds the most sending domains it may (limit: 10 by default, or the project's own cap the platform set).What to do: Delete a domain you no longer send from (DELETE /v1/email/domains/{domain}), then add the new one — or ask us to raise the project's cap.
EMAIL_DOMAIN_NOT_VERIFIED409The project sends through Amazon SES and its sending domain is not verified (or was removed, or stopped verifying).What to do: Publish the DNS records GET /v1/email/domains/{domain} lists, re-check with POST /v1/email/domains/{domain}/verify, and send once its status is verified.
EMAIL_DOMAIN_OVERLAP409Another project holds a parent domain or a subdomain of it. Like EMAIL_DOMAIN_CLAIMED, it carries a challenge.What to do: Publish the challenge TXT record and claim again: unverified claims give way at once. A verified holder never does — contact us.
EMAIL_DOMAIN_PENDING_LIMIT409The project already has 3 sending domains that are not yet verified.What to do: Verify one of them (publish its records, then POST /v1/email/domains/{domain}/verify) or delete one you do not need, then add the new one.
EMAIL_DOMAIN_RELEASING409The domain’s previous identity is still being deleted.What to do: Retry the claim in a few minutes.
EMAIL_DOMAIN_UNAVAILABLE409An identity for the domain exists in the sending account outside any project.What to do: Retrying will not help: contact us to have it cleared.
EMAIL_SENDING_SUSPENDED409The project’s email is suspended: its hard-bounce or complaint rate on the shared sending account crossed the threshold.What to do: Retrying will not help until support reviews and lifts it: contact us, and stop mailing the addresses that bounce or complain.
EMAIL_SUPPRESSED409The address — the recipient’s or a copy’s — is on the project’s suppression list; reason is hard_bounce, soft_bounce, complaint or manual. See Email.What to do: Do not send to that address — drop a suppressed copy from cc or bcc. Remove the entry (DELETE /v1/email/suppressions/{suppressionId}) only once you know the address takes your mail again; a soft_bounce lapses by itself after 7 days.
ENTITLEMENT_MESSAGING_DISABLED403Messaging is not enabled for this project (it is calling-only). GET /v1/me shows the project's entitlements.What to do: A project cannot turn messaging on itself: the platform, or the partner that manages the project, enables it. Contact us; retrying will not help until then.
FROM_NOT_ALLOWED409email.from or senderId is not one of the project’s senders: not under a verified sending domain, nor the SMTP account’s own address.What to do: Send from an address under one of your verified sending domains (GET /v1/email/domains), or from the SMTP account’s own address.
MESSAGING_SENDER_RESTRICTED409The sending WhatsApp number is restricted, disabled or quality-flagged; the SMS header is not active; or the email account is switched off in the console.What to do: Send from another sender (senderId; GET /v1/whatsapp/account shows each number’s status and qualityRating, GET /v1/sms/senders each header’s), or switch the email account back on in Settings → Channels → Email. A header becomes usable once the platform activates it.
RECIPIENT_EMAIL_REQUIRED422An email to a contact who has no email address.What to do: Send with to.email when you know the address (the contact with it is used, or created), or reach this contact on another channel.
SUPPRESSION_FORCE_REQUIRED409Removing a complaint suppression needs ?force=true&reason=…. Removing it does not reopen the contact’s email consent.What to do: Only if the recipient asked for your mail again, repeat the delete with ?force=true&reason=…; both are recorded in the audit trail.