Create a workspace

POST

/workspaces

curl --request POST \
  --url https://api.sendtruss.com/v1/workspaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "reference": "example", "timezone": "example", "locale": "example" }'

• Production

One workspace per customer of yours, named by your own reference for that customer, so you can address it as ref: plus the reference from then on.

Authorizations

• http

Request Body^required

Media typeapplication/json

object

name

required

Your customer’s name, as your platform shows it. It can’t be an email address.

string

<= 128 characters

reference

required

Your own id for the customer, unique among your live workspaces. Address the workspace as ref: plus this.

string

/^[A-Za-z0-9._-]{1,128}$/

timezone

The workspace’s time zone, such as Europe/Lisbon; its days start at midnight there. Defaults to UTC.

string

<= 64 characters

locale

The language its email falls back to for a contact with none, such as en or pt-BR. Defaults to en.

string

<= 16 characters /^[A-Za-z]{2,3}(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?(-([A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*$/

Example^generated

{
  "name": "example",
  "reference": "example",
  "timezone": "example",
  "locale": "example"
}

Responses

201

WorkspaceResource

Media typeapplication/json

object

data

required

WorkspaceResource

object

id

required

string

reference

required

Your reference for the customer.

string | null

name

required

string

timezone

required

string

locale

required

string

status

required

string

Allowed values: active suspended

created_at

required

string | null

sending

required

Whether email can go out from the workspace.

object

state

required

ready; blocked while your sending domain is missing or not verified, with the reason below; or waiting for a short while once your domain can send, while the workspace itself is set up to send.

string

Allowed values: ready waiting blocked

reason

required

Why it is blocked: suspended, no_identity when you have no sending domain, or identity_not_sendable when it isn’t verified. Null otherwise.

string | null

health

required

How recipients are treating the workspace’s email. A workspace whose bounces or complaints run high is throttled, then paused, so it can’t harm your other workspaces.

object

state

required

ramping while it builds a sending history, established, throttled or paused.

string

reason

required

What moved it into its state, or null.

string | null

since

required

When it entered its state.

string | null

Example

{
  "data": {
    "status": "active",
    "sending": {
      "state": "ready"
    }
  }
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

401

The API key is missing, malformed, revoked or expired.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: unauthenticated

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "unauthenticated"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

409

Refused because of the resource’s current state. The code says why.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: reference_taken workspace_ceiling_reached

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "reference_taken"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

422

The request is invalid. The code says why, and errors names each field at fault.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: validation_failed

errors

required

Each field that failed validation, by its path in the request, with its messages.

object

key

additional properties

Array<string>

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "validation_failed"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

429

Too many requests. Wait for the seconds in Retry-After.

Media typeapplication/json

object

message

required

What went wrong, for a person to read. It may change, so branch on code.

string

code

required

What went wrong, for your code to branch on. A new code is not a breaking change.

string

Allowed values: rate_limited

doc_url

required

The entry on our errors page that explains this code.

string format: uri

request_id

required

This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.

string format: uuid

Example

{
  "code": "rate_limited"
}

Headers

Request-Id

required

string format: uuid

This request’s id. Quote it when you ask us about the request.

Retry-After

integer

Seconds to wait before trying again.