samva-dev Scheduled Messages API
One-off scheduled message timers
One-off scheduled message timers
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/samva-dev:samva-dev-scheduled-messages-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Samva Scheduled Messages API
version: 1.0.0
description: Samva is the email API for your app. Send transactional email in one typed call. Delivery events and customer replies come back as signed webhooks, and replies thread to the email they answer.
servers:
- url: https://api.samva.dev
security: []
tags:
- name: Scheduled Messages
description: One-off scheduled message timers
paths:
/v1/messages/scheduled:
post:
tags:
- Scheduled Messages
operationId: scheduledMessages.create
parameters:
- name: idempotency-key
in: header
schema:
anyOf:
- type: string
minLength: 1
maxLength: 255
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 255
- type: 'null'
required: false
security:
- apiKey: []
responses:
'201':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledMessage'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: FlagDisabledError | ForbiddenError
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/FlagDisabledError'
- $ref: '#/components/schemas/ForbiddenError'
'409':
description: ConflictError
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'502':
description: ExternalServiceError
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalServiceError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Schedules a message for dispatch at the absolute ISO-8601 timestamp supplied in scheduledFor. Requires `messages:create` or the send permission of the channel it sends on, such as `email:send`. Optional timezone is validated IANA display metadata only and never changes the execution instant.
summary: Schedule a message
requestBody:
content:
application/json:
schema:
type: object
properties:
send:
$ref: '#/components/schemas/DispatchSendMessagePayload'
scheduledFor:
type: string
x-samva-schema: AbsoluteInstant
timezone:
anyOf:
- $ref: '#/components/schemas/IanaTimezone'
- type: 'null'
referenceId:
anyOf:
- type: string
- type: 'null'
required:
- send
- scheduledFor
additionalProperties: false
required: true
x-idempotent: true
x-samva-scope: messages:create or email:send
get:
tags:
- Scheduled Messages
operationId: scheduledMessages.list
parameters:
- name: limit
in: query
schema:
anyOf:
- type: integer
maximum: 100
exclusiveMinimum: 0
description: Items per page, at most 100.
- type: 'null'
required: false
- name: cursor
in: query
schema:
anyOf:
- $ref: '#/components/schemas/Cursor'
- type: 'null'
required: false
- name: status
in: query
schema:
anyOf:
- type: string
enum:
- pending
- dispatching
- paused
- dispatched
- cancelled
- failed
- type: 'null'
required: false
security:
- apiKey: []
responses:
'200':
description: ScheduledMessagePage
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledMessagePage'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Returns scheduled messages, soonest send first, optionally filtered by status. Pass `nextCursor` back as `cursor` for the next page; it is null on the last page.
summary: List scheduled messages
x-samva-scope: messages:read
/v1/messages/scheduled/{id}:
get:
tags:
- Scheduled Messages
operationId: scheduledMessages.get
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/ScheduledMessageId'
required: true
security:
- apiKey: []
responses:
'200':
description: ScheduledMessage
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledMessage'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Returns a single scheduled message by its ID.
summary: Get a scheduled message
x-samva-scope: messages:read
/v1/messages/scheduled/{id}/cancel:
post:
tags:
- Scheduled Messages
operationId: scheduledMessages.cancel
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/ScheduledMessageId'
required: true
security:
- apiKey: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
item:
$ref: '#/components/schemas/ScheduledMessage'
required:
- success
- item
additionalProperties: false
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'409':
description: ConflictError
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Cancels a pending scheduled message so it will not be sent, and returns the updated scheduled message.
summary: Cancel a scheduled message
x-samva-scope: messages:update
/v1/messages/scheduled/{id}/resume:
post:
tags:
- Scheduled Messages
operationId: scheduledMessages.resume
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/ScheduledMessageId'
required: true
security:
- apiKey: []
responses:
'200':
description: ScheduledMessage
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledMessage'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'409':
description: ConflictError
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'422':
description: FromAddressRequiredError | ValidationError
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/FromAddressRequiredError'
- $ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'502':
description: ExternalServiceError
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalServiceError'
'503':
description: SenderNotReadyError
content:
application/json:
schema:
$ref: '#/components/schemas/SenderNotReadyError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Explicitly resumes a scheduled message after onboarding review clearance. An overdue message requires either send_now or a new future scheduledFor value.
summary: Resume a review-paused scheduled message
requestBody:
content:
application/json:
schema:
anyOf:
- type: object
properties:
choice:
type: string
enum:
- send_now
required:
- choice
additionalProperties: false
- type: object
properties:
choice:
type: string
enum:
- new_time
scheduledFor:
type: string
x-samva-schema: AbsoluteInstant
required:
- choice
- scheduledFor
additionalProperties: false
required: true
x-samva-scope: messages:update
components:
schemas:
EmailAttachment:
type: object
properties:
filename:
type: string
content:
anyOf:
- type: string
- type: 'null'
mediaId:
anyOf:
- $ref: '#/components/schemas/MediaId'
- type: 'null'
contentType:
type: string
size:
type: integer
maximum: 26214400
exclusiveMinimum: 0
required:
- filename
- contentType
- size
additionalProperties: false
ScheduledMessageId:
type: string
pattern: ^sched_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: ScheduledMessageId
EmailAttachments:
anyOf:
- type: array
items:
$ref: '#/components/schemas/EmailAttachment'
maxItems: 10
- type: 'null'
EmailTrackingOverrideV1:
type: object
properties:
opens:
type: boolean
description: Override open tracking for this send. Omit to inherit the organization default. A recipient tracking opt-out always disables tracking.
clicks:
type: boolean
description: Override click tracking for this send. Omit to inherit the organization default. A recipient tracking opt-out always disables tracking.
additionalProperties: false
description: Requested per-send engagement tracking policy. Recipient opt-out takes precedence, then explicit fields, organization defaults, and product defaults.
ConflictError:
type: object
properties:
_tag:
type: string
enum:
- ConflictError
message:
type: string
resource:
type: string
id:
anyOf:
- type: string
- type: 'null'
required:
- _tag
- message
- resource
additionalProperties: false
x-category:
- conflict
x-retryable: false
ValidationError:
type: object
properties:
_tag:
type: string
enum:
- ValidationError
message:
type: string
fields:
anyOf:
- type: object
additionalProperties:
type: array
items:
type: string
- type: 'null'
required:
- _tag
- message
additionalProperties: false
x-category:
- validation
x-retryable: false
ScheduledMessage:
type: object
properties:
id:
$ref: '#/components/schemas/ScheduledMessageId'
status:
type: string
enum:
- pending
- dispatching
- paused
- dispatched
- cancelled
- failed
scheduledFor:
type: string
timezone:
type: string
send:
$ref: '#/components/schemas/StoredSendMessagePayload'
messageId:
anyOf:
- $ref: '#/components/schemas/MessageId'
- type: 'null'
idempotencyKey:
anyOf:
- type: string
- type: 'null'
referenceId:
anyOf:
- type: string
- type: 'null'
failureReason:
anyOf:
- type: string
- type: 'null'
attempts:
type: number
createdBy:
anyOf:
- type: string
- type: 'null'
actorEmail:
type: string
memberRole:
type: string
createdAt:
type: string
updatedAt:
type: string
required:
- id
- status
- scheduledFor
- timezone
- send
- messageId
- idempotencyKey
- referenceId
- failureReason
- attempts
- createdBy
- actorEmail
- memberRole
- createdAt
- updatedAt
additionalProperties: false
EmailCcRecipients:
anyOf:
- type: array
items:
$ref: '#/components/schemas/EmailRecipient'
- type: 'null'
- type: 'null'
ExternalServiceError:
type: object
properties:
_tag:
type: string
enum:
- ExternalServiceError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
ScheduledMessagePage:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ScheduledMessage'
nextCursor:
anyOf:
- type: string
- type: 'null'
required:
- items
- nextCursor
additionalProperties: false
StoredSendMessagePayload:
type: object
properties:
conversationId:
anyOf:
- $ref: '#/components/schemas/ConversationId'
- type: 'null'
- type: 'null'
metadata:
$ref: '#/components/schemas/MessageMetadata'
channel:
type: string
enum:
- email
to:
type: array
items:
$ref: '#/components/schemas/SavedEmailRecipient'
minItems: 1
cc:
anyOf:
- type: array
items:
$ref: '#/components/schemas/SavedEmailRecipient'
- type: 'null'
- type: 'null'
bcc:
anyOf:
- type: array
items:
$ref: '#/components/schemas/SavedEmailRecipient'
- type: 'null'
- type: 'null'
from:
anyOf:
- type: object
properties:
email:
type: string
minLength: 1
name:
anyOf:
- type: string
- type: 'null'
required:
- email
additionalProperties: false
- type: 'null'
email:
$ref: '#/components/schemas/EmailContent'
required:
- channel
- to
- email
additionalProperties: false
GatewayTimeoutError:
type: object
properties:
_tag:
type: string
enum:
- GatewayTimeoutError
message:
type: string
retryAfterSeconds:
type: number
required:
- _tag
- message
- retryAfterSeconds
additionalProperties: false
x-category:
- transient
x-retryable: true
EmailRecipient:
anyOf:
- type: object
properties:
contactId:
$ref: '#/components/schemas/ContactId'
required:
- contactId
additionalProperties: false
- type: object
properties:
email:
type: string
name:
anyOf:
- type: string
maxLength: 120
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 120
- type: 'null'
displayName:
anyOf:
- type: string
maxLength: 120
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 120
- type: 'null'
- type: 'null'
required:
- email
additionalProperties: false
TemplateData:
anyOf:
- $ref: '#/components/schemas/JsonObject'
- type: 'null'
ContactId:
type: string
pattern: ^contact_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: ContactId
JsonObject:
type: object
additionalProperties:
$ref: '#/components/schemas/JsonValue'
TemplateId:
type: string
pattern: ^tmpl_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: TemplateId
InternalError:
type: object
properties:
_tag:
type: string
enum:
- InternalError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
TemplatePublicationId:
type: string
pattern: ^tpub_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: TemplatePublicationId
MessageMetadata:
anyOf:
- type: object
additionalProperties:
$ref: '#/components/schemas/JsonValue'
- type: 'null'
EmailCustomHeaders:
type: object
additionalProperties:
type: string
maxProperties: 11
description: Custom headers copied onto the outgoing message. Each name is an RFC 5322 field name and each value is one non-empty line of printable ASCII. Names Samva or the transport own are rejected.
ReplyToAddresses:
anyOf:
- type: array
items:
type: string
- type: 'null'
- type: 'null'
TopicId:
type: string
pattern: ^unsub_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: TopicId
ForbiddenError:
type: object
properties:
_tag:
type: string
enum:
- ForbiddenError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- auth
x-retryable: false
EmailSender:
anyOf:
- type: object
properties:
email:
type: string
minLength: 1
name:
anyOf:
- type: string
maxLength: 120
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 120
- type: 'null'
required:
- email
additionalProperties: false
- type: 'null'
EmailFooterOverride:
type: object
properties:
enabled:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
EmailContent:
type: object
properties:
subject:
anyOf:
- type: string
- type: 'null'
html:
anyOf:
- type: string
- type: 'null'
text:
anyOf:
- type: string
- type: 'null'
attachments:
$ref: '#/components/schemas/EmailAttachments'
publicationId:
$ref: '#/components/schemas/TemplatePublicationId'
inputContractId:
$ref: '#/components/schemas/TemplateInputContractId'
templateId:
anyOf:
- $ref: '#/components/schemas/TemplateId'
- type: 'null'
templateSlug:
anyOf:
- type: string
pattern: ^(?=.{1,100}$)[a-z0-9]+(?:-[a-z0-9]+)*$
- type: 'null'
templateData:
$ref: '#/components/schemas/TemplateData'
locale:
$ref: '#/components/schemas/RenderLocale'
timeZone:
$ref: '#/components/schemas/RenderTimeZone'
inReplyToMessageId:
anyOf:
- $ref: '#/components/schemas/MessageId'
- type: 'null'
replyTo:
$ref: '#/components/schemas/ReplyToAddresses'
topicId:
anyOf:
- $ref: '#/components/schemas/TopicId'
- type: 'null'
- type: 'null'
description: The topic for this send. Omit to inherit the template topic; null disables topic inheritance for a direct send. Campaigns require a topic.
tracking:
$ref: '#/components/schemas/EmailTrackingOverrideV1'
footer:
$ref: '#/components/schemas/EmailFooterOverride'
headers:
anyOf:
- $ref: '#/components/schemas/EmailCustomHeaders'
- type: 'null'
additionalProperties: false
UnauthorizedError:
type: object
properties:
_tag:
type: string
enum:
- UnauthorizedError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- auth
x-retryable: false
EmailRecipients:
type: array
items:
$ref: '#/components/schemas/EmailRecipient'
minItems: 1
FlagDisabledError:
type: object
properties:
_tag:
type: string
enum:
- FlagDisabledError
flag:
type: string
message:
type: string
required:
- _tag
- flag
- message
additionalProperties: false
x-retryable: false
IanaTimezone:
type: string
MediaId:
type: string
pattern: ^media_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: MediaId
SavedEmailRecipient:
anyOf:
- type: object
properties:
contactId:
$ref: '#/components/schemas/ContactId'
required:
- contactId
additionalProperties: false
- type: object
properties:
email:
type: string
name:
anyOf:
- type: string
- type: 'null'
displayName:
anyOf:
- type: string
- type: 'null'
- type: 'null'
required:
- email
additionalProperties: false
ConversationId:
type: string
pattern: ^conv_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: ConversationId
TemplateInputContractId:
type: string
pattern: ^tcon_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: TemplateInputContractId
RenderLocale:
type: string
maxLength: 64
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 64
Cursor:
type: string
SenderNotReadyError:
type: object
properties:
_tag:
type: string
enum:
- SenderNotReadyError
message:
type: string
sender:
type: string
retryAfterSeconds:
anyOf:
- type: number
- type: 'null'
required:
- _tag
- message
- sender
additionalProperties: false
x-category:
- transient
x-retryable: true
EmailDispatchContent:
type: object
properties:
subject:
anyOf:
- type: string
- type: 'null'
html:
anyOf:
- type: string
- type: 'null'
text:
anyOf:
- type: string
- type: 'null'
attachments:
$ref: '#/components/schemas/EmailAttachments'
publicationId:
$ref: '#/components/schemas/TemplatePublicationId'
inputContractId:
$ref: '#/components/schemas/TemplateInputContractId'
templateId:
anyOf:
- $ref: '#/components/schemas/TemplateId'
- type: 'null'
templateSlug:
anyOf:
- type: string
pattern: ^(?=.{1,100}$)[a-z0-9]+(?:-[a-z0-9]+)*$
- type: 'null'
templateData:
$ref: '#/components/schemas/TemplateData'
locale:
$ref: '#/components/schemas/RenderLocale'
timeZone:
$ref: '#/components/schemas/RenderTimeZone'
inReplyToMessageId:
anyOf:
- $ref: '#/components/schemas/MessageId'
- type: 'null'
replyTo:
$ref: '#/components/schemas/ReplyToAddresses'
topicId:
anyOf:
- $ref: '#/components/schemas/TopicId'
- type: 'null'
- type: 'null'
description: The topic for this send. Omit to inherit the template topic; null disables topic inheritance for a direct send. Campaigns require a topic.
tracking:
$ref: '#/components/schemas/EmailTrackingOverrideV1'
footer:
$ref: '#/components/schemas/EmailFooterOverride'
headers:
anyOf:
- $ref: '#/components/schemas/EmailCustomHeaders'
- type: 'null'
additionalProperties: false
MessageId:
type: string
pattern: ^msg_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: MessageId
RenderTimeZone:
type: string
maxLength: 64
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 64
FromAddressRequiredError:
type: object
properties:
_tag:
type: string
enum:
- FromAddressRequiredError
message:
type: string
verifiedDomains:
type: array
items:
type: string
required:
- _tag
- message
- verifiedDomains
additionalProperties: false
x-category:
- validation
x-retryable: false
JsonValue:
anyOf:
- type: string
- type: number
- type: boolean
- type: 'null'
- type: array
items:
$ref: '#/components/schemas/JsonValue'
- type: object
additionalProperties:
$ref: '#/components/schemas/JsonValue'
EmailBccRecipients:
anyOf:
- type: array
items:
$ref: '#/components/schemas/EmailRecipient'
- type: 'null'
- type: 'null'
ResourceNotFoundError:
type: object
properties:
_tag:
type: string
enum:
- ResourceNotFoundError
resource:
type: string
id:
type: string
message:
type: string
required:
- _tag
- resource
- id
- message
additionalProperties: false
x-category:
- notFound
x-retryable: false
DispatchSendMessagePayload:
type: object
properties:
conversationId:
anyOf:
- $ref: '#/components/schemas/ConversationId'
- type: 'null'
- type: 'null'
metadata:
$ref: '#/components/schemas/MessageMetadata'
channel:
type: string
enum:
- email
to:
$ref: '#/components/schemas/EmailRecipients'
cc:
$ref: '#/components/schemas/EmailCcRecipients'
bcc:
$ref: '#/components/schemas/EmailBccRecipients'
from:
$ref: '#/components/schemas/EmailSender'
email:
$ref: '#/components/schemas/EmailDispatchContent'
required:
- channel
- to
- email
additionalProperties: false
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header