Send email and WhatsApp

Send templates to an address your backend knows, through your own AWS or mail account.

⏱ About 15 minutes after your email or WhatsApp account is ready

Claspine Messaging sends email and WhatsApp messages from templates, through your own provider account: Amazon SES or any SMTP service for email, AWS End User Messaging for WhatsApp. Recipients see your name and your provider bills you directly; Claspine charges nothing per message. Your backend sends to an address or number it already knows. Claspine does not keep a list of your users: it keeps the full address only until the message is accepted or has failed (72 hours at most), then only a masked form like r***@example.com for the history. Self-hosted Claspine sends the same way, through the providers you configure (Notifications in self-hosted Claspine).

Words you’ll see

API key: A long secret string that lets software use your account, like a password made for programs. Anyone who has it can spend on your account, so treat it like a password.
Test recipient: An email address or phone number your project may message with test API keys (sp_test_). Keeps an unfinished integration from messaging real customers.
Message template (WhatsApp): A message text Meta approved in advance, with numbered blanks {{1}}, {{2}}. WhatsApp only lets businesses start a conversation with an approved template.

Before you start

Email: an Amazon SES account or an SMTP service (see the email guides). WhatsApp: a WhatsApp Business Account linked in AWS (see the WhatsApp guide).

Steps

Set up a channel: follow Email with Amazon SES, Email with an SMTP service or WhatsApp. Each ends with Check in the console showing everything ready.
Open Messaging → Templates and add a template your code will send, for example order.shipped. Email: a subject and text with {{name}} where your code fills in values. WhatsApp: choose an approved Meta template and the variable for each of its numbered blanks.
Open Messaging → Test, add yourself as a test recipient (an email address confirms with a code; a phone number by ticking that it is yours), and send a test.
Use a key with the messages:send permission: a new project’s first test key has it; for a live key, tick it under API keys. Keys made before messaging existed cannot send messages.
Send from your backend: POST /api/v1/messages with channel, to, template and variables, or claspine.messages.send({...}) with the Node.js SDK. Give each message an Idempotency-Key (for example order-A-42-shipped) so a retry never sends it twice.
An sp_test_ key reaches only your confirmed test recipients; switch to an sp_live_ key when you are ready to message real customers.

Node.js; any language works the same over HTTP (see Recipes).

import { ClaspineClient } from '@grahmur-org/claspine-client';

const claspine = new ClaspineClient({ apiKey: process.env.SPINE_API_KEY });
const message = await claspine.messages.send({
  channel: 'whatsapp', to: '+14155550123', template: 'order.shipped',
  variables: { name: 'Ravi', order: 'A-42' }, idempotencyKey: 'order-A-42-shipped',
});
// message.status: ACCEPTED, RETRYABLE_FAILURE (retried for you) or TERMINAL_FAILURE (see failureDetail)

What goes where in Claspine

Console field	Value
API key scope	messages:send to send, messages:read to read the history from your code.
to	An email address, or a phone number in international form starting with + (e.g. +14155550123).
template	The name of a template under Messaging → Templates.

Keep it safe

Send only messages people expect: transactional messages (orders, reminders, receipts), or marketing they agreed to. You are the sender with your provider and with Meta.
Claspine never sends with another project’s account or its own; a project without a ready channel gets MESSAGING_NOT_CONFIGURED.
Messages are limited per minute and per month by plan, so a bug cannot flood anyone. A suspended project sends nothing.

Claspine stores the values encrypted, never shows them again in full, and never sends them to your app or SDK.

If something goes wrong

403 TEST_RECIPIENT_REQUIRED.: You used an sp_test_ key and the recipient is not a confirmed test recipient. Add them under Messaging → Test, or use an sp_live_ key.
409 MESSAGING_NOT_CONFIGURED.: The channel is not set up: Messaging → Setup shows the next step.
404 MESSAGE_TEMPLATE_NOT_FOUND.: No template with that name for that channel; names are exact, e.g. order.shipped.
400 MESSAGE_VARIABLES_MISSING.: Send a value for every {{name}} in the template (the error lists the missing ones).
Status TERMINAL_FAILURE.: Read failureDetail: it is your provider’s answer, for example an unverified SES address or a WhatsApp template not approved in that language.

Provider documentation

← All setup guides