Skip to main content

Email and SMS API

Trivore ID can send free-form email and SMS messages on your behalf, using the same delivery infrastructure — and, for SMS, the same routing and billing — configured for the platform's own messages. See Email and SMS for that configuration.

This is for sending your own, arbitrary messages. If you're instead trying to verify a user's email address or mobile number as part of a sign-in or contact-info-change flow, use the dedicated verification endpoints described in Implementing changing of user's email address or mobile number instead.

Sending email​

curl -X POST "https://{your-id-server}/api/rest/v1/email/send" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["[email protected]"],
    "subject": "Your export is ready",
    "text": "Your requested data export is ready to download.",
    "html": "<p>Your requested data export is ready to download.</p>"
  }'

Requires the EMAIL_SEND permission. to, cc, and bcc each accept a list of addresses. Provide text, html, or both — a client that can't render HTML falls back to text. from and replyTo are optional and default to the system's configured sender; attachments and custom headers are also supported.

There's also a version of this endpoint scoped to a Group — POST /api/rest/v1/group/{groupId}/email/send — which sends the same message to every member of the group at once, rather than to addresses you specify individually.

Sending email with a template​

For anything sent more than once — notifications, reports, and similar — an email template is usually a better fit than building the message yourself on every send. A template holds the subject, HTML, and text content (with per-locale translations and placeholders), authored and maintained in the Management UI or imported/exported as JSON; the API only needs to supply the recipients and any per-send values to fill into it.

Find the template's ID by listing templates (requires EMAIL_TEMPLATE_VIEW):

curl "https://{your-id-server}/api/rest/v1/emailtemplate" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

Then send it:

curl -X POST "https://{your-id-server}/api/rest/v1/emailtemplate/{emailTemplateId}/send" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "userId": "{userId}", "properties": { "orderId": "1234" } },
      { "emailAddress": "[email protected]", "preferredLocale": "fi" }
    ],
    "properties": { "serviceName": "Acme Corp Portal" }
  }'

Requires EMAIL_SEND, the same as sending a free-form email. Each entry in recipients gets its own message: userId looks up the user's email address, locale, and other details automatically (make them available to the template as ${recipientUser} — see Built-in properties); emailAddress sends to an address that isn't necessarily tied to a user account at all, with preferredLocale filling in for the missing user's own locale preference. A recipient's own properties are merged on top of the top-level properties shared by the whole send, so per-recipient values (like orderId above) can override or add to common ones (like serviceName) — both become available in the template under those names, following the placeholder syntax described in Template engine.

Email templates can also be created, updated, and deleted through the API — POST/GET/PUT/DELETE on /api/rest/v1/emailtemplate (and /{emailTemplateId}), using the same JSON shape as the Management UI's own template import/export feature.

Sending SMS​

curl -X POST "https://{your-id-server}/api/rest/v1/sms/send" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+358401234567",
    "text": "Your verification code is 123456"
  }'

Unlike email, sending an SMS depends on several pieces of system configuration being in place first — a matching routing plan and billing plan for the destination region, and the custom SMS feature and REST API sending both being enabled. If any of these is missing, the send fails even with otherwise-correct credentials and permissions; see SMS for how to configure them.

from is optional (up to 11 alphanumeric characters); if omitted, a default sender is used. Set fromRequired to false if it's acceptable for the message to go out through a gateway that doesn't support a custom sender at all, rather than failing when one isn't available. clientRef is a free-form identifier of your choosing, echoed back in delivery reports so you can match a report to the message that caused it.

A GET /api/rest/v1/sms/send variant of the same call accepts the same fields as query parameters instead of a JSON body, if that's more convenient for your use case.

Last updated on