Samva
DashboardAPI
ChannelsPlatformMailboxesDevelopersEmail templatesIntegrationsAPI Reference
Messages

Send a message

Sends a message on the requested channel and returns its receipt (id, status, and why it waits when it does) with a 201 Created status.

POST
/v1/messages

Sends a message on the requested channel and returns its receipt (id, status, and why it waits when it does) with a 201 Created status. Requires messages:create or the send permission of the channel it sends on, such as email:send. channel selects the payload variant. Repeating an identical request with the same optional Idempotency-Key header returns the original receipt; reusing the key for different content returns a conflict.

Authorization

apiKey
headerx-api-key<token>

Header Parameters

idempotency-key?string

Optional org-scoped key that makes a send idempotent. Repeating a request with the same key and identical payload replays the original 201 response; reusing the key with different content returns 409.

Match^[\s\S]{1,255}$

Request Body

application/json
  1. body
conversationId?|null|null
metadata?|null
channel*"email"
Value in"email"
to*array<|>
Items1 <= items
cc?array<|>|null|null
bcc?array<|>|null|null
from?|null
email*

Response Body

MessageReceipt

application/json
  1. response
id*MessageId
Match^msg_[0-9a-hjkmnp-tv-z]{16,24}$
status*string
Value in"pending""scheduled""queued""processing""sent""delivered""read""failed""bounced""complained"
waitReason*|null
reviewExpectedAt*string|null
skippedRecipients*array<>
createdAt*string
Example Request
import { createClient } from "samva";const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });const result = await samva.messages.send({  "channel": "email",  "to": [    {      "contactId": "example"    }  ],  "email": {    "subject": "Hello",    "text": "Hello from Samva."  }});
Example Response
{  "id": "string",  "status": "pending",  "waitReason": "rate",  "reviewExpectedAt": "string",  "skippedRecipients": [    {      "address": "string",      "reason": "bounce",      "topicId": "string"    }  ],  "createdAt": "string"}

Related documentation

Delete a message

Permanently deletes a message by its ID. Use this endpoint to delete a message through the Samva email API.

Validate an email message

Resolves recipients, sender, and inline or published-template content without sending anything, creating contacts or messages, or counting toward your quota.