Communications API

Direct email, SMS, and phone-call endpoints.

Use the Communications API when your application already knows it wants to send an email, text a user, or place a phone call. These endpoints are useful for server-side orchestration, background jobs, and provider-triggered workflows that do not need the full Chat API.

Provider setup still matters

These endpoints still use the selected agent's communication credentials. Your organization must have working SendGrid and Twilio setup before direct sends can succeed, and the selected agent must have the matching built-in tool enabled:send-email-invite, send-sms, or place-call.

Endpoints

POST/v1/emails

POST/v1/sms

POST/v1/calls

Shared Context

Field	Type	Description
`agent_id`	`string`	Required. Agent slug or ID used for credential resolution, policy, and billing.
`end_user_id`	`UUID`	Galadri's internal end-user UUID. Optional for email. Required for SMS and calls unless session_id already resolves to an end user. If you only have your own user ID, resolve it through the Users API first.
`session_id`	`UUID`	Optional. Useful for continuity, audit linkage, and resolving end-user context from an existing session.

POST /v1/emails

Send direct emails and calendar invites through the selected agent's email credential.

Supported actions

Field	Type	Description
`send_email`	`action`	Send a plain email. Requires to, subject, and body_html or body_text.
`send_invite`	`action`	Send a calendar invite email. Requires to, title, and start_datetime.
`cancel_invite`	`action`	Cancel a previously sent invite by schedule_id.

Email request fields

Parameter	Type	Description
`agent_id`required	string	Agent slug or ID.
`action`required	"send_email" \| "send_invite" \| "cancel_invite"	Email action to execute.
`to`	string	Recipient email address.
`subject`	string	Subject line for send_email.
`body_html`	string	HTML body for send_email.
`body_text`	string	Plain-text body for send_email.
`title`	string	Event title for send_invite.
`start_datetime`	string	ISO 8601 with timezone offset for send_invite.
`duration_minutes`	integer	Optional duration for send_invite.
`location`	string	Optional location for send_invite.
`description`	string	Optional event description for send_invite.
`schedule_id`	string	Required for cancel_invite.
`end_user_id`	UUID	Optional internal Galadri end-user UUID for email workflows.
`session_id`	UUID	Optional session context.

Direct email send

curl -X POST https://api.galadri.com/v1/emails \
  -H "Authorization: Bearer gld_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "main-agent",
    "action": "send_email",
    "to": "rob@example.com",
    "subject": "Service update",
    "body_text": "Your appointment is confirmed for tomorrow at 10:00 AM."
  }'

Email response

{
  "status": "success",
  "data": {
    "sent": true,
    "to": "rob@example.com",
    "subject": "Service update",
    "thread_id": null
  }
}

Email responses include a thread ID when the request includes end_user_id or a session_id that resolves to an end user.

POST /v1/sms

Send SMS or MMS directly through the selected agent's Twilio credential.

SMS request fields

Parameter	Type	Description
`agent_id`required	string	Agent slug or ID.
`to`required	string	Recipient phone number. E.164 format preferred (for example "+15551234567").
`message`required	string	Message text.
`media_url`	string	Optional image URL for MMS.
`thread_id`	string	Optional existing SMS thread ID.
`end_user_id`	UUID	Internal Galadri end-user UUID. Required unless session_id resolves to an end user.
`session_id`	UUID	Optional session context.

Direct SMS send

curl -X POST https://api.galadri.com/v1/sms \
  -H "Authorization: Bearer gld_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "main-agent",
    "end_user_id": "5361a22a-d4a9-4c57-b98b-c70c72f5865f",
    "to": "+15551234567",
    "message": "Your vehicle is ready for pickup."
  }'

SMS response

{
  "status": "success",
  "data": {
    "sent": true,
    "thread_id": "550e8400-e29b-41d4-a716-446655440000",
    "segments": 1,
    "has_media": false
  }
}

SMS and call context

Direct SMS and call requests require end-user context. Provide end_user_id directly or provide a session_id that already belongs to the end user.

POST /v1/calls

Initiate an outbound AI phone call through the selected agent's Twilio credential.

Call request fields

Parameter	Type	Description
`agent_id`required	string	Agent slug or ID.
`to`required	string	Recipient phone number. E.164 format preferred (for example "+15551234567").
`purpose`required	string	What the AI should discuss or accomplish on the call.
`prompt`	string	Optional call-specific prompt override.
`tools`	string[]	Optional subset of tool slugs the voice agent can use on this call.
`end_user_id`	UUID	Internal Galadri end-user UUID. Required unless session_id resolves to an end user.
`session_id`	UUID	Optional session context.

Direct call initiation

curl -X POST https://api.galadri.com/v1/calls \
  -H "Authorization: Bearer gld_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "main-agent",
    "end_user_id": "5361a22a-d4a9-4c57-b98b-c70c72f5865f",
    "to": "+15551234567",
    "purpose": "Confirm tomorrow's appointment",
    "prompt": "Your mission is to confirm the appointment and answer any follow-up questions briefly.",
    "tools": ["google-maps-search", "send-sms"]
  }'

Call response

{
  "status": "success",
  "data": {
    "initiated": true,
    "call_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Errors

Validation, missing-tool, provider, and internal errors use the standard error envelope when possible. A 402 insufficient-credit response may return a plain string error for compatibility with the chat endpoint.

Error response

{
  "error": {
    "code": "validation_error",
    "message": "Tool \"send-sms\" is not available for this agent"
  }
}

For channel behavior, inbound setup, and credential ownership, see Communications. For the main conversational entry point, see Chat API.

Data ModelNext