Communications API

Server-side endpoints for email, SMS, and AI phone calls.

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

Endpoints

Shared Context

POST /v1/emails

Send direct emails and calendar invites through the selected agent's email credential. Plain emails are sent immediately. Calendar invites can create, update, or cancel saved schedule records. Provider click tracking is disabled for these operational emails so authored links stay direct.

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."
  }'

{
  "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. Agent-authored outbound emails include unsubscribe content and one-click unsubscribe headers. One-click unsubscribe mutates preference state only on POST, while normal link opens show a confirmation page. Galadri blocks future sends after a recipient opts out of email from that sender.

POST /v1/sms

Queue SMS or MMS through the selected agent's Twilio credential. Galadri checks sender-recipient SMS preferences before queueing, so opted-out recipients return an error instead of a queued callback workflow. Successful responses mean Galadri accepted the message and stored it for delivery. Carrier delivery can still fail later. On the first outbound text from a sender number to a recipient, Galadri adds a short disclosure that identifies the message type and explains how to opt out.

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."
  }'

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

POST /v1/calls

Initiate an outbound AI phone call through the selected agent's Twilio credential. Successful responses mean Galadri created the call session and started call initiation. The live call and post-call summary continue asynchronously. The JSON request body is capped at 256 KB.

If the recipient or another outside contact calls back, Galadri first matches the callback by destination credential and outside contact. Generic inbound calls use the credential default agent, but a matched callback resumes with the agent that initiated the outreach. During the live call, that agent can use its enabled communication tools to call, text, email, or notify another contact when that is the right next step.

When the request includes a chat session_id and the follow-up route is chat, Galadri records the call result in that same session and can run a new assistant turn so the user receives the update in the original thread. Follow-up delivery is idempotent for the same callback result, so provider retries do not duplicate the same chat, SMS, or email follow-up. Push follow-up webhooks include a stable delivery id when one is available so your backend can apply the same dedupe rule.

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.",
    "follow_up_channel": "email"
  }'

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

Errors

Validation, unavailable capability, provider, and internal errors use the standard structured error envelope when possible. A 402 insufficient-credit response may return a plain string error for compatibility with other Galadri endpoints.

{
  "error": {
    "code": "validation_error",
    "message": "end_user_id or session_id is required for SMS"
  }
}

Related Docs

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