Email messaging model

Every email Samva sends or receives is a message. An immediate send, a scheduled send, and each recipient of a campaign run all create messages the same way, so they share one set of records and one stream of events. Learn the model once and it applies to every way you send.

One message per emailCopy Anchor Link

A send returns a message ID (msg_…). That ID follows the email through its lifecycle: the message status you read from the API, the entries in Observe → Activity, and the messageId in every message event all refer to it. An inbound reply is a message too, with its own ID.

email.send() in the SDK and POST /v1/messages create the same message. Email and the messages API explains the two request shapes and when to use each.

Shared recordsCopy Anchor Link

Messages point at records your organization keeps across sends:

• Contacts. Address a send to { contactId } instead of repeating an email address. Samva keeps each contact's identities, tags, and status.
• Conversations. An inbound reply threads into the conversation of the email it answers, and a send with a conversationId continues that thread.
• Templates. Reference a published, versioned template by templateId or templateSlug instead of sending inline content.
• Events. Delivery outcomes, inbound email, and changes to contacts and conversations arrive at your webhook endpoints as signed events.

Scheduled and campaign emailCopy Anchor Link

A scheduled email creates its message when it dispatches, and the scheduled message then reports that messageId. A campaign run creates one message per recipient. From that point both behave exactly like an immediate send: the same statuses, suppression checks, delivery events, and reply threading.

RelatedCopy Anchor Link