Notifications

Send transactional notifications (quotes, invoices, appointment reminders) to customers via email and SMS

The Notifications API lets you trigger transactional notifications to customers — sending a quote for review, sending an invoice, or reminding a customer of an upcoming appointment. The system uses the workspace's existing templates and channel preferences (email and SMS), so notifications sent via the API look and behave exactly like ones sent from the dashboard.

A single endpoint, POST /api/v1/notifications, handles all supported notification types. You specify the type along with the parent entity to notify about.

Authentication

Authorization: Bearer wk_your_api_key

Required scope: notifications:write (or the write wildcard).

Supported notification types

`type`	What it does	`module_id` is	Channels
`quote_to_customer`	Sends a quote to its linked contact and transitions the quote status to `awaiting_response`	a quote ID	Email (and SMS, if the workspace + contact are configured for it)
`invoice_to_customer`	Sends an invoice to its linked contact and transitions the invoice status to `sent`	an invoice ID	Email
`appointment_reminder`	Sends an "appointment is coming up soon" reminder to the event's linked contact	an event ID	Email (and SMS, if configured)

Channel selection is automatic — it follows the workspace's customer-notification settings (Settings → Customer Notifications) and the contact's SMS opt-in status. The API does not currently support forcing a specific channel.

Send a notification

POST /api/v1/notifications

Request body:

Field	Type	Required	Description
`type`	string	Yes	One of: `quote_to_customer`, `invoice_to_customer`, `appointment_reminder`
`module_id`	integer	Yes	ID of the parent entity in your workspace. The expected entity type is determined by `type` (quote, invoice, or event — see the table above).

curl -X POST https://app.bluesuite.com/api/v1/notifications \
  -H "Authorization: Bearer wk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "quote_to_customer",
    "module_id": 42
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "queued": true,
    "type": "quote_to_customer",
    "module": "quotes",
    "module_id": 42,
    "recipient": {
      "contact_id": 7,
      "email": "jane@example.com"
    }
  }
}

The response echoes back module (derived from type) for convenience, but you do not pass it in the request.

queued: true means the notification was successfully handed off to the email/SMS pipeline. Actual delivery happens asynchronously through AWS SES (and Twilio, for SMS). Delivery status appears in the dashboard's email log; this endpoint does not return delivery confirmation.

Channel behaviour

Email

Always sent when the contact has an email address and the workspace has email notifications enabled for the type. Subject lines and bodies use the workspace's customizable templates — same templates the dashboard's "Send" button uses.

SMS

Sent when all of the following are true:

The workspace has Twilio configured (Settings → Integrations → SMS).
The workspace's plan includes SMS notifications.
The contact has opted in to SMS (contact.info.sms_consent.opt_in === true).
The customer-notification settings have SMS enabled for the type.

If any condition is false, SMS is silently skipped — the response still reports queued: true if email was sent.

Email limits

Each workspace has a monthly email allowance based on plan tier. If the limit has been reached, the notification is not sent and the API returns 200 with the queued response — but no email actually leaves. The workspace's admin will receive an internal notification about the limit being hit. Inspect the email log to confirm delivery.

Side effects

Type	Side effect
`quote_to_customer`	The quote's status transitions to `awaiting_response` (matching the dashboard's Send button). That status change fires a `quotes_awaiting_response` internal notification to workspace admins/managers.
`invoice_to_customer`	The invoice's status transitions to `sent`, which fires an `invoices_sent` internal notification to workspace admins/managers.
`appointment_reminder`	None. The event's assigned users get their own `appointments_soon` notifications from the daily reminder cron when the appointment is actually within the reminder window — this endpoint does not notify them on demand.

Internal notifications respect each user's notification preferences (Settings → My Notifications) and the workspace's internal-notification settings (Settings → Internal Notifications) — same as notifications triggered from the dashboard.

Error Responses

Status	When
`400`	Validation error (missing fields, invalid `type`, or the entity has no contact / contact has no email)
`401`	Missing or invalid API key
`403`	API key lacks the `notifications:write` scope
`404`	Entity not found in your workspace

{
  "success": false,
  "error": "Quote has no contact with an email address"
}

Tips

Customer-notification preferences are workspace-level: if quotes_awaiting_response is disabled in the workspace's settings, the API call returns success but no email is sent. Same as the dashboard.
The reminder content for appointment_reminder is the "appointment is coming up soon" template, suitable for triggering 24 hours before. There is no separate "first reminder" vs "second reminder" — call the endpoint each time you want a reminder dispatched.
This endpoint does not currently support sending arbitrary internal notifications to workspace users. That is on the roadmap.

On this page