Get started
Send an email from your domain
Claim a sending domain, publish its DNS records, verify it and send a transactional email — then follow deliveries, bounces and complaints.
Email goes out from your project’s own sending domain, never from Trovacast’s. This quickstart claims a subdomain, verifies it and sends an order confirmation.
1. What you need
- Access to your domain’s DNS. A subdomain such as
mail.acme.comis recommended: it keeps sending reputation apart from your people’s own mail and needs no change at the apex. - A key with
email:manage,email:read,contacts:write,messages:writeandmessages:read— see Authentication and Scopes. - Email set up for the project with Amazon SES in the console (Settings → Email). A project sending through its own SMTP server skips the domain steps and sends from that account’s address.
2. Claim the 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"
}'{
"object": "email_domain",
"domain": "mail.acme.com",
"status": "pending",
"dkimStatus": "PENDING",
"mailFromDomain": "bounce.mail.acme.com",
"mailFromStatus": "PENDING",
"records": [
{
"kind": "dkim",
"type": "CNAME",
"name": "abc123._domainkey.mail.acme.com",
"value": "abc123.dkim.amazonses.com",
"priority": null,
"required": true,
"purpose": "Signs outgoing mail so receivers can prove it really came from this domain.",
"verdict": "missing",
"observed": []
}
],
"verifiedAt": null
}3. Publish the DNS records
Add every record with required: true at your DNS provider exactly as given — three DKIM CNAMEs, and the MAIL FROM MX and SPF records. DMARC is advisory. Each record’s verdict is what Trovacast’s resolver last saw (ok, missing, mismatch, unchecked), so you can tell which one is wrong.
4. Verify
Trovacast re-checks unverified domains every few minutes; ask for a check now once the records are in. The domain sends only when its status is verified: Amazon SES must verify it and Trovacast’s resolver must see its DKIM records.
curl -X POST 'https://api.trovacast.com/v1/email/domains/mail.acme.com/verify' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"5. Send the email
email.from must be an address under a verified domain (409 FROM_NOT_ALLOWED otherwise); omit it to use the account’s default. A transactional email needs no opt-in but is refused by an opt-out; a marketing one needs email marketing: opted_in and carries an unsubscribe footer. Sending by to.email creates the contact if it does not exist.
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",
"from": "orders@mail.acme.com",
"fromName": "Acme Orders",
"replyTo": "support@acme.com"
},
"metadata": {
"orderId": "1001"
}
}'{
"object": "message",
"channel": "email",
"type": "text",
"status": "queued",
"email": {
"subject": "Your order #1001 is confirmed",
"from": "orders@mail.acme.com",
"to": "a•••@example.com",
"cc": [],
"bcc": [],
"attachments": []
},
"metadata": {
"orderId": "1001"
}
}6. Follow deliveries, bounces and complaints
Subscribe to message.delivered, message.failed and message.complained. A hard bounce fails the message (SES_BOUNCE_PERMANENT) and suppresses the address for good; a spam complaint suppresses it and opts the contact out of email (contact.consent.updated). Later sends to a suppressed address are refused 409 EMAIL_SUPPRESSED — see Email.