Schedule a message

Parameters

Request body

• send_atstringrequired

  ISO 8601. At least 60 seconds ahead, at most 30 days. A time we cannot honour is refused rather than rounded, and a past `send_at` is refused rather than sent immediately — it almost always means a timezone was dropped somewhere in your stack.

Request

curl -X POST 'https://app.mailyte.com/api/v1/messages/scheduled' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": [
      "ada@example.com"
    ],
    "from": "hello@yourdomain.com",
    "subject": "Your weekly summary",
    "text": "Here is what happened this week.",
    "send_at": "2026-09-21T09:00:00Z"
  }'

const response = await fetch('https://app.mailyte.com/api/v1/messages/scheduled', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": [
      "ada@example.com"
    ],
    "from": "hello@yourdomain.com",
    "subject": "Your weekly summary",
    "text": "Here is what happened this week.",
    "send_at": "2026-09-21T09:00:00Z"
  }),
});
const { data } = await response.json();

import requests
response = requests.post(
    "https://app.mailyte.com/api/v1/messages/scheduled",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={
      "to": [
        "ada@example.com"
      ],
      "from": "hello@yourdomain.com",
      "subject": "Your weekly summary",
      "text": "Here is what happened this week.",
      "send_at": "2026-09-21T09:00:00Z"
    },
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->post('https://app.mailyte.com/api/v1/messages/scheduled', [
    'to' => [
        'ada@example.com',
    ],
    'from' => 'hello@yourdomain.com',
    'subject' => 'Your weekly summary',
    'text' => 'Here is what happened this week.',
    'send_at' => '2026-09-21T09:00:00Z',
]);

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/messages/scheduled")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  "to": [
    "ada@example.com"
  ],
  "from": "hello@yourdomain.com",
  "subject": "Your weekly summary",
  "text": "Here is what happened this week.",
  "send_at": "2026-09-21T09:00:00Z"
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

Response

201 with the `scheduled_message`. Use its `id` to list, inspect or cancel it.

• dataobject

  A message accepted now and submitted at `send_at`. It is not a `message`: a message has left, and this has not. Once it goes, `message_id` names the message it became.

  • objectstringscheduled_message
  • idstring

    Address this with `GET` and `DELETE /messages/scheduled/{id}`. It identifies the SCHEDULE, not the message — see `message_id`.

  • statusstringscheduled | sending | sent | cancelled | failed

    One of: `scheduled` (waiting), `sending` (claimed for submission — the window in which cancelling is no longer possible), `sent`, `cancelled`, `failed`.

  • modestringlive | test

    `test` when a test key accepted this message: it runs the whole flow — validation, scheduling, listing, cancelling — and submits nothing when it comes due. Captured when the message is accepted, not when it is sent, because test mode is a property of the KEY and the sweep has no key to read. `live` is the default.

  • send_atstring

    When it is due. Honoured to the minute — we refuse a `send_at` less than 60 seconds out rather than promise a precision we do not have.

  • fromstring

    The sender, as scheduled.

  • toarray<string>

    The recipients, as scheduled. `cc` and `bcc` are held but not published back — a Bcc that reappears in a readable response is a Bcc that leaked.

  • subjectstring

    `null` MEANS NONE WAS SET — a message may legitimately have no subject, and a template supplies its own at render time.

  • message_idstring

    The Message-ID it got when it left, for following it into the delivery log. `null` MEANS IT HAS NOT LEFT — still scheduled, cancelled, or failed. Never a placeholder.

  • sent_atstring

    When it was submitted. `null` MEANS IT HAS NOT BEEN.

  • cancelled_atstring

    When it was cancelled. `null` MEANS IT WAS NOT.

  • failure_reasonstring

    Why it could not be sent, in words. `null` MEANS NOTHING WENT WRONG — not that the reason is unknown. Only a `failed` row carries one. Suppression and rate limits are evaluated when the message leaves, not when it was accepted, so a message scheduled on Monday for somebody who unsubscribes on Tuesday fails here and says so.

  • created_atstring

    When it was accepted.

Returned inside the standard envelope.

Errors

Every status, with what causes it and what to do, is on the error reference.