Platforms and workspaces

Your platform is the account. A workspace is one of your customers inside it. You create one workspace per customer through the API, give it your own id for that customer, and from then on address it as ref: plus that id. You never need to store our ids.

What belongs to the platform, and what to a workspace

The platform owns everything that should mean the same thing for every customer:

• your API keys;
• your sending domain;
• attribute definitions, so {{ attributes.plan }} means the same field in every workspace;
• event types and their templates;
• webhook endpoints and signing secrets.

A workspace owns what belongs to one customer: their contacts and tags, the events you emit for them, and the email we send for them. One customer’s contacts are never visible from another’s workspace.

Your key reaches every workspace of your platform

There is one kind of key. It can do everything the API does, for every workspace of your platform. Keys are created on the console by your platform’s owners, and shown once. You can hold several live keys at once, which is how you rotate: create a new key, deploy it, then revoke the old one. A key never expires on its own.

Every request sends the key as a bearer token:

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

A workspace of another platform answers 404, exactly like one that doesn’t exist. Its existence is not your key’s business.

Requests are limited per platform, across all your keys. Past the limit you get a 429 with the code rate_limited and a Retry-After header saying how many seconds to wait.

Creating a workspace

Create a workspace with a name and your reference for the customer:

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",
    "timezone": "America/Denver",
    "locale": "en"
  }'

• reference is 1 to 128 letters, digits, ., _ and -. It must be unique among your live workspaces; a taken one is refused with reference_taken.
• timezone decides where the workspace’s days start. It defaults to UTC.
• locale is the language its email falls back to for a contact with none. It defaults to en.
• name is your customer’s name as your platform shows it. It can’t be an email address.

Your platform has a workspace limit, set in your contract. Past it, a create is refused with workspace_ceiling_reached.

Addressing a workspace

Every path that names a workspace takes either our id or ref: plus your reference: /workspaces/ref:cust_4821/contacts. A reference needs no URL encoding, because its characters are all safe in a path. You can change the reference later, along with the name, timezone and locale.

Get a workspace to see two states worth watching:

• sending.state is ready when email can go out. It is blocked while your sending domain is missing or not verified, and while the workspace is suspended, with a reason: no_identity when you have no sending domain yet, identity_not_sendable when its records aren’t verified, or suspended. It is waiting for a short while once your domain can send, while the workspace itself is set up to send; an emit in that window is accepted and goes out when it’s ready.
• health.state is how recipients are treating the workspace’s email: ramping while it builds a sending history, then established. A workspace whose bounces or complaints run high is throttled, then paused, so one customer’s list can’t harm your other customers. A health pause always stops marketing email, and only we lift it. Separately, the sending service can stop a workspace’s mail, which stops transactional email too, and health may not show it. The signal for that is each emit’s message ending in message.failed with the reason sending_paused.

Suspend, resume and delete

Suspend a workspace when a customer stops paying or you need to stop their email. Nothing is sent from it, on either stream, until you resume it. An emit into it is refused with workspace_suspended. Its data stays readable and writable, so you can keep syncing a customer you expect back. Only you can resume it.

Delete a workspace when the customer is gone. Sending stops at once and the workspace answers 404 from then on. Its contacts and history are removed 30 days later. Its reference is free for a new workspace straight away. The API can’t undo a delete; if you deleted one by mistake, contact us within those 30 days.

You won’t get a webhook for any of these: your backend made the call, so it already knows.