Emit an event
const url = 'https://api.sendtruss.com/v1/workspaces/example/events';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"type":"example","idempotency_key":"example","recipient":{"contact":"example","email":"example"},"payload":{"additionalProperty":"example"},"attachments":[{"filename":"example","content":"example"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.sendtruss.com/v1/workspaces/example/events \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "type": "example", "idempotency_key": "example", "recipient": { "contact": "example", "email": "example" }, "payload": { "additionalProperty": "example" }, "attachments": [ { "filename": "example", "content": "example" } ] }'Tell us something happened for one recipient. When the event type has a
default template, we render it with the payload and send it from your
domain; either way the event is recorded. The answer says what became of
the email: queued, or suppressed when the address is suppressed.
The idempotency key makes a retry safe: the same key with the same body
answers with the first response and the Idempotent-Replayed header,
without sending again. A refused emit records nothing, its key included,
so you can fix it and send it with the same key.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”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 Bodyrequired
Section titled “Request Bodyrequired”object
The event type’s name, as you registered it.
Your unique key for this event, up to 255 printable ASCII characters, no spaces.
Who the event is for: a contact in the workspace, by our id or as ref: plus your reference, or an email address. Exactly one of the two.
object
The event’s fields, checked against its type’s schema. Send {} for a type with no fields.
object
Files to attach to the email, at most 10 and 10,000,000 bytes in all once decoded. Each content is base64. PDF, PNG, JPEG, GIF, WebP and iCalendar files are accepted, and the file name’s extension must match its content.
object
Examplegenerated
{ "type": "example", "idempotency_key": "example", "recipient": { "contact": "example", "email": "example" }, "payload": { "additionalProperty": "example" }, "attachments": [ { "filename": "example", "content": "example" } ]}Responses
Section titled “Responses”The recorded event, and the email it sent, or null in message when the type has no default template.
object
object
object
object
Example
{ "data": { "message": { "state": "queued" } }}Headers
Section titled “Headers”Present, as true, when this is the stored answer to an earlier emit with the same key.
This request’s id. Quote it when you ask us about the request.
The API key is missing, malformed, revoked or expired.
object
What went wrong, for a person to read. It may change, so branch on code.
What went wrong, for your code to branch on. A new code is not a breaking change.
The entry on our errors page that explains this code.
This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.
Example
{ "code": "unauthenticated"}Headers
Section titled “Headers”This request’s id. Quote it when you ask us about the request.
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.
object
What went wrong, for a person to read. It may change, so branch on code.
What went wrong, for your code to branch on. A new code is not a breaking change.
The entry on our errors page that explains this code.
This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.
Example
{ "code": "not_found"}Headers
Section titled “Headers”This request’s id. Quote it when you ask us about the request.
Refused because of the resource’s current state. The code says why.
object
What went wrong, for a person to read. It may change, so branch on code.
What went wrong, for your code to branch on. A new code is not a breaking change.
The entry on our errors page that explains this code.
This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.
Example
{ "code": "idempotency_key_reused"}Headers
Section titled “Headers”This request’s id. Quote it when you ask us about the request.
The request is invalid. The code says why, and errors names each field at fault.
object
What went wrong, for a person to read. It may change, so branch on code.
What went wrong, for your code to branch on. A new code is not a breaking change.
Each field that failed validation, by its path in the request, with its messages.
object
The entry on our errors page that explains this code.
This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.
Example
{ "code": "validation_failed"}Headers
Section titled “Headers”This request’s id. Quote it when you ask us about the request.
Too many requests. Wait for the seconds in Retry-After.
object
What went wrong, for a person to read. It may change, so branch on code.
What went wrong, for your code to branch on. A new code is not a breaking change.
The entry on our errors page that explains this code.
This request’s id, the same as its Request-Id header. Quote it when you ask us about the request.
Example
{ "code": "rate_limited"}Headers
Section titled “Headers”This request’s id. Quote it when you ask us about the request.
Seconds to wait before trying again.