Quickstart

This page takes you from your first sign-in to the console to an email sent from your own domain, landing in your own inbox, in under an hour. The one step nobody can speed up is DNS, so you start it first and keep working while it propagates. Until it’s done, you test against a simulator address that plays a delivery without sending anything.

You need access to your domain’s DNS, a terminal with curl, and an inbox you can read. Every request on this page calls https://api.sendtruss.com/v1, reads your API key from $SENDTRUSS_API_KEY, and names your customer and your user by your own references, so nothing needs copying out of one answer into the next request.

1. Sign in to the console (2 minutes)

Accept the invitation we emailed you and sign in. The clock starts here.

2. Add your DNS records (5 minutes, then it propagates)

Open the console’s domain screen. It lists the DNS records your domain needs, with a button to copy each. Add them all at your DNS provider, exactly as shown, and come back. Don’t wait for them to verify: the screen checks on its own, and the rest of this page works while it does.

DNS usually takes minutes. If your DNS changes go through a ticket queue at your company, the hour is gone at this step, and that’s expected: do steps 3 to 8 now and step 9 when the records are in. Sending domain and DNS explains what each record is for.

3. Create an API key (2 minutes)

Open the console’s API keys screen and create a key. It is shown once, on a card with three fields to copy: the key itself, a line that puts it in your shell, and your first call. Copy the second, the export line, into your terminal, since every example on this site reads the key from it:

export SENDTRUSS_API_KEY='<your new key>'

The third is your first call, which lists your workspaces:

curl https://api.sendtruss.com/v1/workspaces \
  -H "Authorization: Bearer $SENDTRUSS_API_KEY"

It answers 200 OK with no workspaces yet:

{
  "data": [],
  "links": {"first": null, "last": null, "prev": null, "next": null},
  "meta": {
    "path": "https://api.sendtruss.com/v1/workspaces",
    "per_page": 50,
    "next_cursor": null,
    "prev_cursor": null
  }
}

If it answers an error

• unauthenticated: the key didn’t arrive. Check echo $SENDTRUSS_API_KEY prints it, and that you ran the export in this shell.

4. Create a workspace (2 minutes)

A workspace holds one of your customers: their contacts, their sending and their health. Create one with your own id for that customer as its reference:

curl -X POST https://api.sendtruss.com/v1/workspaces \
  -H "Authorization: Bearer $SENDTRUSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pine Valley Campground", "reference": "cust_4821"}'

It answers 201 Created:

{
  "data": {
    "id": "01k76wz8q4m2r7s0t3v5x9y1ab",
    "reference": "cust_4821",
    "name": "Pine Valley Campground",
    "timezone": "UTC",
    "locale": "en",
    "status": "active",
    "created_at": "2026-10-08T12:00:00+00:00",
    "sending": {"state": "blocked", "reason": "identity_not_sendable"},
    "health": {"state": "ramping", "reason": null, "since": "2026-10-08T12:00:00+00:00"}
  }
}

sending is blocked because your domain hasn’t verified yet. From now on, every request names this workspace as ref:cust_4821. Platforms and workspaces explains what else a workspace holds.

If it answers an error

• reference_taken: you already made a workspace with this reference. Carry on with it.
• validation_failed: errors names the field. A reference uses letters, digits, _, - and ..

5. Register a webhook endpoint (5 minutes)

What happens to your email comes back to your backend as webhooks. Register an endpoint now, so it is there for your first email. Its URL must be public HTTPS, since we never send webhooks to private addresses. If your handler isn’t public yet, a request-inspection service gives you a URL in a click and shows you every webhook that arrives.

curl -X POST https://api.sendtruss.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $SENDTRUSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.yourplatform.com/sendtruss",
    "types": ["message.delivered", "message.bounced", "message.complained", "message.suppressed", "message.failed", "message.expired"]
  }'

It answers 201 Created:

{
  "data": {
    "id": "01k76x2m4p6r8t0v2x4z6b8d0f",
    "url": "https://hooks.yourplatform.com/sendtruss",
    "types": ["message.delivered", "message.bounced", "message.complained", "message.suppressed", "message.failed", "message.expired"],
    "created_at": "2026-10-08T12:00:00+00:00",
    "updated_at": "2026-10-08T12:00:00+00:00"
  },
  "signing_secret": {
    "id": "01k76wq3r5t7v9x1z3b5d7f9h2",
    "secret": "st_whsec_4mQx9Vb2Lr7TzK1nWc8Hs3Dp6Yf0Ga5JeUo2Ri9XkNt",
    "last_four": "XkNt",
    "created_at": "2026-10-08T12:00:00+00:00"
  }
}

Keep signing_secret.secret: it is shown this once, and your handler needs it to verify each webhook.

If it answers an error

• A url_ code, such as url_not_https or url_address_refused: the URL isn’t one we can send to. The code says why.
• unknown_type: one of the types is misspelled.

6. Push a contact (3 minutes)

A contact is a person in a workspace. Push one by your own id for that user, with your own email address so you can watch the last step arrive:

curl -X PUT https://api.sendtruss.com/v1/workspaces/ref:cust_4821/contacts/ref:user_1 \
  -H "Authorization: Bearer $SENDTRUSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourplatform.com"}'

Replace the address with yours. The same call updates the contact when it exists, answering 200 OK; the first time it answers 201 Created:

{
  "data": {
    "id": "01k76x0a1b2c3d4e5f6g7h8j9k",
    "reference": "user_1",
    "email": "you@yourplatform.com",
    "status": "pending",
    "locale": null,
    "marketing": null,
    "pixel_consent_at": null,
    "attributes": {},
    "tags": [],
    "created_at": "2026-10-08T12:00:00+00:00",
    "updated_at": "2026-10-08T12:00:00+00:00"
  }
}

When you connect your real platform, push your existing users with the batch upsert, up to 500 at a time, before you send your first campaign. Sync your contacts shows how.

If it answers an error

• email_taken: another contact in this workspace has the address. contact names it.
• validation_failed: errors names the field, usually email.

7. Register an event type and give it a template (5 minutes)

An event type is something that happens on your platform that should send an email, with the fields that email needs. Register one:

curl -X PUT https://api.sendtruss.com/v1/event-types/welcome \
  -H "Authorization: Bearer $SENDTRUSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields": [{"name": "first_name", "type": "string", "required": true}]}'

It answers 201 Created:

{
  "data": {
    "name": "welcome",
    "fields": [{"name": "first_name", "type": "string", "required": true, "fallback": null}],
    "created_at": "2026-10-08T12:00:00+00:00",
    "updated_at": "2026-10-08T12:00:00+00:00"
  }
}

Now give it a template. Open the event type in the console’s template editor, write a subject and a heading, put {{ event.first_name }} somewhere, and save. That is its default template, used in every workspace. If you’d rather keep templates in code, save it through the API instead; Send transactional email for your events shows how.

If it answers an error

• schema_change_not_additive: an event type called welcome already exists with other fields. Pick another name for this walk-through.
• validation_failed: errors names the field at fault.

8. Emit to the simulator (2 minutes)

Emit the event to delivered@simulator.sendtruss.com. A simulator address works while your domain is still pending, sends nothing out, and plays a delivery:

curl -X POST https://api.sendtruss.com/v1/workspaces/ref:cust_4821/events \
  -H "Authorization: Bearer $SENDTRUSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "welcome",
    "idempotency_key": "welcome-simulator-1",
    "recipient": {"email": "delivered@simulator.sendtruss.com"},
    "payload": {"first_name": "Ada"}
  }'

It answers 202 Accepted:

{
  "data": {
    "id": "01k76x5c7e9g1j3m5p7r9t1v3x",
    "type": "welcome",
    "idempotency_key": "welcome-simulator-1",
    "contact": null,
    "message": {
      "id": "01k76x6d8f0h2k4n6q8s0v2y4a",
      "state": "queued",
      "template_version_id": "01k76x4b6d8f0h2k4n6q8s0v2y",
      "fell_back": [],
      "simulated": true
    },
    "created_at": "2026-10-08T12:00:00Z"
  }
}

Within a few seconds your endpoint receives message.delivered with "simulated": true. Testing lists the addresses that play a bounce and a complaint.

If it answers an error

• message is null: the event type has no default template yet. Save one (step 7) and emit again with a new idempotency key.
• idempotency_key_reused: you changed the body but kept the key. Use a new key.
• validation_failed: the payload doesn’t match the event type’s fields, or the address isn’t one of the simulator’s three. errors says which.

9. Send a real email (5 minutes, once DNS is done)

Check the console’s domain screen shows your domain verified. Then emit the same event to your contact, by your reference for them:

curl -X POST https://api.sendtruss.com/v1/workspaces/ref:cust_4821/events \
  -H "Authorization: Bearer $SENDTRUSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "welcome",
    "idempotency_key": "welcome-user_1",
    "recipient": {"contact": "ref:user_1"},
    "payload": {"first_name": "Ada"}
  }'

It answers 202 Accepted:

{
  "data": {
    "id": "01k76x7e9g1j3m5p7r9t1v3x5z",
    "type": "welcome",
    "idempotency_key": "welcome-user_1",
    "contact": {"id": "01k76x0a1b2c3d4e5f6g7h8j9k", "reference": "user_1"},
    "message": {
      "id": "01k76x1p6c9d2e4f7g8h0j3k5m",
      "state": "queued",
      "template_version_id": "01k76x4b6d8f0h2k4n6q8s0v2y",
      "fell_back": [],
      "simulated": false
    },
    "created_at": "2026-10-08T12:00:00Z"
  }
}

Watch your inbox: the email arrives from your own domain. Your endpoint receives message.delivered, this time with "simulated": false and your contact’s reference. You’re done.

If it answers an error

• domain_not_sendable: your domain hasn’t verified yet. Check the domain screen, and try again when every record is verified.
• validation_failed under recipient.contact: no contact has the reference user_1 in this workspace. Push it first (step 6).

If the email doesn’t arrive, Where did my email go? follows it from the emit to the inbox.

Where next

• How SendTruss works, for the whole model on one page.
• Handle and verify webhooks, to turn your endpoint into a real handler.
• Go-live checklist, before your customers send real email.