Messaging
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.
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}/verifyre-checks now (unverified domains are also re-checked every few minutes). Onlystatus: verifiedsends: 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(orfailed) and sends through it are refused withEMAIL_DOMAIN_NOT_VERIFIEDuntil it verifies again. DELETE /v1/email/domains/{domain}releases it (with?version=, only that version;409 CONFLICTif it moved).- Limits: 10 domains per project by default (the platform can raise one project's cap; the refusal's
limitsays 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 a400.
Send an 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
contactIdorto: { email }. A send by address uses the project’s contact with that address or creates an email-only one, so it also needscontacts:write. A contact without an address is422 RECIPIENT_EMAIL_REQUIRED. Every refusal once the recipient is known carries itscontactId. - **
type: "text":**email.subject(required; one line, up to 998 characters),textand/oremail.html, andemail.category(required). HTML (up to 256 KB) is sanitized before it is stored: layout, inline styles,classand<style>blocks stay; scripts, event handlers, forms, frames,javascript:anddata:links and CSS that loads anything are removed, and images load over https only. Withouttext, a plain-text part is derived from the HTML. - **
type: "template":** an email template and itsvariables. Values are HTML-escaped into the HTML, which is sanitized again, so a value can never add markup.email.subjectoverrides the template’s subject;textandemail.htmlare not allowed. - From: the account’s default address unless
email.from(withemail.fromName) or an emailsenderIdnames another — under one of the project’s verified sending domains, or the SMTP account’s own address;409 FROM_NOT_ALLOWEDotherwise.email.replyTosets where replies go. - Copies:
email.ccandemail.bcc— at most 20 together, transactional only (marketingwith copies is a400). Each copy is checked like the recipient: a suppressed address is409 EMAIL_SUPPRESSED, one belonging to a contact who opted out is409 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,.icsand.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.
Consent by category
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 reports | Message | Event |
|---|---|---|
| Delivery | delivered | message.delivered |
| Hard bounce | failed, SES_BOUNCE_PERMANENT; the address is suppressed for good | message.failed |
| Soft bounce (SES gave up retrying) | failed, SES_BOUNCE_TRANSIENT; the address is suppressed for 7 days | message.failed |
| Held back by SES’s own account-wide list | failed, SES_ACCOUNT_SUPPRESSED; not added to your list | message.failed |
| Complaint (reported as spam) | Unchanged (it was delivered); the address is suppressed and the contact’s email consent opted out | message.complained, contact.consent.updated |
| Reject or rendering failure | failed, SES_REJECT / SES_RENDERING_FAILURE | message.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.
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
- POST
/v1/messagesSends a message: a WhatsApp template, text, media file or interactive message (or an email or SMS) - POST
/v1/email/domainsClaims a sending domain and returns the DNS records to publish - GET
/v1/email/domainsLists the organization’s sending domains with their DNS records - GET
/v1/email/domains/{domain}Retrieves a sending domain with its DNS records and verdicts - POST
/v1/email/domains/{domain}/verifyRe-checks a sending domain’s DNS records and its status at Amazon SES - DELETE
/v1/email/domains/{domain}Releases a sending domain - POST
/v1/email/suppressionsSuppresses an address (reason `manual`, permanent) - GET
/v1/email/suppressionsLists suppressed addresses (masked), newest first — or looks one address up - GET
/v1/email/suppressions/{suppressionId}Retrieves one suppression - DELETE
/v1/email/suppressions/{suppressionId}Removes a suppression, so the address can be emailed again
Events
| Event | When it is sent | Key scopes |
|---|---|---|
message.sent | The 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: message | messages:read |
message.delivered | A 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: message | messages:read |
message.failed | A message failed for good. message.failure carries { code, reason }. A scheduled message cancelled before it was sent fails with MESSAGE_CANCELED.data: message | messages:read |
message.complained | A 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, message | messages:read |
contact.consent.updated | A contact’s consent on a channel changed. WhatsApp, email or SMS consent moved — a STOP, an unsubscribe, a spam report, a reply, Meta’s own preference, or a write through the API or the console. consent.object names the channel.data: consent, livemode, source | contacts:read |
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
BILLING_INSUFFICIENT_CREDIT | 402 | The 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_UNAVAILABLE | 503 | Your 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_CANCELED | 402 | The 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_DUE | 402 | The 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_SUSPENDED | 402 | The subscription is blocked by the platform.What to do: Retrying will not help until the hold is lifted: contact us. |
CHANNEL_NOT_CONFIGURED | 409 | The 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. |
CONSENT_MARKETING_REQUIRED | 409 | A marketing message to a contact who agreed to updates (transactional or utility messages) only: it needs marketing: opted_in on the channel. See Consent.What to do: Send a non-marketing message instead — a utility template, a transactional email, a service SMS — or record the contact's marketing opt-in once they give it (PUT /v1/contacts/{contactId}/consent/{channel}). |
CONSENT_OPTED_OUT | 409 | The contact opted out on this channel — or, for a marketing message, out of marketing — whether you recorded it or they did (STOP, an unsubscribe, a spam report).What to do: Do not retry. After a marketing opt-out a transactional or utility message may still go; only a new opt-in reopens the channel — theirs, if they opted out themselves. See What a send needs. |
CONSENT_REQUIRED | 409 | No opt-in on file for this kind of message on this channel.What to do: Record the contact's consent with PUT /v1/contacts/{contactId}/consent/{channel} once you have collected it (a WhatsApp or email refusal carries the contactId), then send again. See Record a decision. |
CONTACT_BLOCKED | 409 | The 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_OUT | 409 | On 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_UNAVAILABLE | 503 | Amazon 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_ADDED | 409 | This 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_CLAIMED | 409 | Another 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_LIMIT | 409 | The 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_VERIFIED | 409 | The 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_OVERLAP | 409 | Another 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_LIMIT | 409 | The 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_RELEASING | 409 | The domain’s previous identity is still being deleted.What to do: Retry the claim in a few minutes. |
EMAIL_DOMAIN_UNAVAILABLE | 409 | An 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_SUSPENDED | 409 | The 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_SUPPRESSED | 409 | The 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_DISABLED | 403 | Messaging 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_ALLOWED | 409 | email.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_CONSENT_REQUIRED | 409 | A consent refusal not classified under a more specific consent code (reserved). Treat it like CONSENT_REQUIRED.What to do: Record the contact’s opt-in first (PUT /v1/contacts/{contactId}/consent/{channel}, once you have collected it), then send again. |
MESSAGING_SENDER_RESTRICTED | 409 | The 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_REQUIRED | 422 | An 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_REQUIRED | 409 | Removing 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. |