Update a workspace

PATCH

/workspaces/{workspace}

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

• Production

Send only the fields you are changing.

Authorizations

• http

Parameters

Path Parameters

workspace

required

string

/^(?:[0-9A-Za-z]{26}|ref:[A-Za-z0-9._-]{1,128})$/

The workspace: our id, or ref: plus your reference for it, such as ref:cust_4821. A reference is letters, digits, ., _ and -, up to 128 characters, and needs no URL encoding.

Request Body

Media typeapplication/json

object

name

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

string

<= 128 characters

reference

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

200

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.

404

Nothing is at this path for your key. Another platform’s or another workspace’s resource answers the same as one that doesn’t exist.

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: not_found

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": "not_found"
}

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

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.