Messaging

Gmail

target_app: "gmail" · endpoint /v1/messaging/execute · OAuth — connects per end-user automatically

Setup

No credentials to add — this is per end-user OAuth, not a developer key. Send your user to the Google connect URL (see the Google platform page) once; that single connection unlocks Gmail plus Calendar, Contacts, YouTube, and Sheets together.

Actions

send_email

Send from the connected user's own Gmail — html is optional.

Request body:

{
  "user_id": "...",
  "action": "send_email",
  "payload": { "to": "someone@example.com", "subject": "Hi", "text": "Plain fallback", "html": "<b>Hi</b>" },
  "target_app": "gmail"
}

provider_response.result shape:

{ "id": "...", "threadId": "..." }

list_messages

List the user's 10 most recent inbox messages.

Request body:

{
  "user_id": "...",
  "action": "list_messages",
  "payload": {},
  "target_app": "gmail"
}

provider_response.result shape:

{ "messages": [{"id":"...","threadId":"..."}] }

get_message

Fetch one specific message by ID.

Request body:

{
  "user_id": "...",
  "action": "get_message",
  "payload": { "messageId": "18c9f2a1b3d4e5f6" },
  "target_app": "gmail"
}

provider_response.result shape:

{ "id": "...", "payload": {...} }

Anticipated errors & fixes

400 "No Google token found in Vault for user X. Connect Google first."

Cause: This user_id has never completed the Google OAuth connect flow.

Fix: Send them to /auth/google/connect?user_id=X&callback_url=... first.

Gmail send silently fails after previously working

Cause: Google access tokens expire hourly — if there's no refresh token, it can't auto-renew.

Fix: Reconnect via the OAuth flow (which requests offline access + a refresh token going forward).

401 "Unauthorized: Invalid API key."

Cause: Your eConnect Authorization header is missing, malformed, or the key was regenerated/revoked.

Fix: Copy your api_key fresh from the eConnect dashboard and confirm the header reads exactly "Authorization: Bearer <key>".

429 "Too many requests"

Cause: You've exceeded your plan's per-minute rate limit.

Fix: Wait a minute and retry, or upgrade your plan for a higher per-minute limit.

429 "Monthly API limit exceeded"

Cause: You've used your plan's full monthly request allowance.

Fix: Wait for your next billing cycle reset, or upgrade to a plan with a higher monthly limit.

← Back to all platforms