Send a message

Send an email. The call comes back as soon as the message is safely accepted and the sending itself follows a moment later, so watch `GET /messages` to see how it went. **Where the words come from.** Send `content` and `content_type` and we send exactly that. Otherwise we look for a template, in this order: 1. The template you named in `template_id`. 2. Your own template for this kind of message, language and channel. 3. Our standard template for that kind of message. 4. Nothing found — the `values` you sent go out as plain text. **Filling in the blanks.** A template has blanks like `{{.first_name}}`, and `values` supplies what goes in them. A `url` is filled in for you where the message has somewhere to point, unless your template sets its own. **Two things to know.** Email is the only way to reach people at the moment, so asking for another channel comes back as `422`. Sending later is not available either: a `scheduled_at` in the future is refused rather than quietly sent now. The message is sent on behalf of the organization you are working in. **Retrying safely.** Send an `Idempotency-Key` header and a repeat of the same call returns the message you already queued instead of sending a second one. **How much you may send.** Sending is capped per hour, per organization and per recipient. Over either cap comes back as `429`. Requires the `notifications.messages.create` permission.

POST
/messages/send

Authorization

AuthorizationBearer <token>

The access token returned after a successful sign-in, sent as Authorization: Bearer <access_token>.

It identifies the person and the organization they are working in, and it lasts about fifteen minutes. When it runs out, use their refresh token at POST /auth/refresh-token instead of asking them to sign in again.

In: header

Header Parameters

Idempotency-Key?string

Your own identifier for this send. Repeat it to retry a call safely: a second request carrying a key we have already accepted returns the first message rather than sending a second one. Any string you can regenerate for the same send works; a UUID is the usual choice.

Lengthlength <= 128

Request Body

application/json

The message to send.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.dual.network/messages/send" \  -H "Content-Type: application/json" \  -d '{    "to": "person@example.com",    "action_type": "custom",    "template_id": "665f1c2d4b1a2c3d4e5f6ad0",    "language": "en",    "values": {      "first_name": "Alex",      "ticket": "A-114"    }  }'
{
  "id": "665f1c2d4b1a2c3d4e5f6b01"
}
{
  "code": 3,
  "message": "Key: 'limit' Error:Field validation for 'limit' failed on the 'lte' tag"
}

{
  "code": 16,
  "message": "no auth provided"
}

{
  "code": 7,
  "message": "forbidden"
}

{
  "code": 3,
  "message": "notification channel is disabled"
}

{
  "code": 8,
  "message": "too many requests"
}
{
  "code": 13,
  "message": "internal error"
}
{
  "code": 14,
  "message": "service unavailable"
}