Trovacast

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.com is 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:write and messages: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

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"
}'
201 Created — the records to publish (json)
{
  "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.

Re-check the domain
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.

Send an order confirmation
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"
  }
}'
202 Accepted — queued (json)
{
  "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.

Next steps