Communications

Base URL: $CONNECTOR_API

Exchange an enrollment token for a connector session token

Logs

POST /communications/registrations

Exchanges a platform-issued enrollment token for a connector identity and returns 201 with connector_id, a session token (used as a Bearer token on the job endpoints) and the tenant IDs the connector may serve. name (up to 120 characters) and at least one channel (email or push) are required. Each registration uses one of the enrollment token's allowed uses, and an expired, exhausted or unknown token returns 401. No other authentication is required.

Body application/json

tokenstring · required

One-time communication connector enrollment token

namestring · required
channelsarray of string · required
hostnamestring · optional
agent_versionstring · optional

Returns

201 Connector registered

Errors 401

curl -X POST "$CONNECTOR_API/communications/registrations" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "token": "token",
  "name": "Ana Matsinhe",
  "channels": [
    "channel"
  ],
  "hostname": "hostname",
  "agent_version": "agent version"
}'
Response 201

Connector registered

Long-poll for the next message to deliver

Logs

POST /communications/jobs/request

Leases the next pending message delivery job for the authenticated connector, optionally narrowed to some of its registered channels and granted tenants (400 if the narrowing leaves nothing). With wait_timeout_seconds the call long-polls up to 50 seconds; it returns 204 when no job became available. A leased job is held for one minute and must be renewed with heartbeat, completed or released. Requires the connector session token as a Bearer token.

Returns

200 A leased job

Errors 401

curl -X POST "$CONNECTOR_API/communications/jobs/request" \
  -H "Authorization: Bearer sk_test_..."
Response 200

A leased job

Renew a job lease

Logs

POST /communications/jobs/{id}/heartbeat

Extends the connector's lease on a job by one minute from now and records the connector as alive, returning 204. Call it while a delivery takes longer than the lease; if the lease already expired or the job is held by another connector, the call returns 409 and the job must not be completed.

Parameters

idstring · path · required

ID of the communication job whose lease is renewed.

Returns

204 Lease renewed

Errors 409

curl -X POST "$CONNECTOR_API/communications/jobs/{id}/heartbeat" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Lease renewed

Release communication job

Logs

POST /communications/jobs/{id}/release

Return a job this connector holds no credentials for to the queue

Gives a leased job back to the queue without a delivery attempt, returning 204; the job becomes pending again and the attempt is not counted against its retry limit. Use it when the connector cannot deliver now, for example during shutdown. Returns 409 when the connector no longer holds the lease.

Parameters

idstring · path · required

ID of the communication job to release.

Returns

204 Job returned to the queue without consuming an attempt

Errors 409

curl -X POST "$CONNECTOR_API/communications/jobs/{id}/release" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Job returned to the queue without consuming an attempt

Report a delivery outcome

Logs

POST /communications/jobs/{id}/complete

Report a delivery outcome; the message content is then erased

Reports the delivery outcome of a leased job with status sent, delivered or failed, plus an optional provider reference, status code and failure reason, and returns 204. A failed job with failure_class transient (the default) is requeued with a backoff while attempts and the delivery window remain; permanent failures and successes are final, and the message content is erased. Returns 409 when the connector no longer holds the lease.

Parameters

idstring · path · required

ID of the communication job leased by this connector.

Returns

204 Outcome recorded

Errors 409

curl -X POST "$CONNECTOR_API/communications/jobs/{id}/complete" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Outcome recorded