Messages

Queue an outbound iMessage

Creates a draft that the on-device connector will send from the customer's Apple ID as an iMessage (or as SMS fallback if the recipient is not on iMessage).

post/messages

Request

  • Base URL: https://api.automessage.app/v1
  • URL: https://api.automessage.app/v1/messages
  • Auth: API key in header X-API-KEY

Request body

tostring

Recipient identifier for a 1:1 send. Phone numbers are normalized to E.164 (e.g. +14155550123); email addresses are accepted for Apple ID recipients. Omit when sending into an existing thread with conversationId.

conversationIdstring

Send into an existing conversation you own (its id from GET /v1/conversations), including group chats — the only way to message a group. The draft is then addressed by chatGUID with an empty to; a 1:1 thread resolves to its recipient handle. 404 not_found when the thread is not yours. A reply into an existing group never counts against the new-outreach limit.

bodystring required
scheduledAtstring date-time

Optional ISO-8601 send-at time.

Example request

{
  "to": "+14155550123",
  "conversationId": "zjueBDq8rN2pLx0vT7aK",
  "body": "hi from autoMessage",
  "attachments": [
    {
      "mimeType": "image/png"
    }
  ]
}

Response

Message queued. When the connector will hold it instead of sending at once, meta.queued says why: outreach_limit_reached (rolling-24h new-outreach cap; limit, used, resumesAt), send_paused (the account's sending is paused — after several sends failed to deliver, by the burst detector, or by hand; a human resumes from the dashboard unless resumesAt is set) or thread_delivery_failing (the last message into that conversation was not delivered; held until they reply or Messages' own retry lands). Never a 429.

guidstring required

Apple chat.db message GUID.

conversationstring required
bodystring required
outboundboolean required

True if we sent it.

contactstring

E.164 phone or email of the counterparty.

referencestring nullable

Message this replies to, if any.

deliveredAtstring date-time nullable
deliveredboolean nullable

Outbound only: chat.db is_delivered — a recipient device acknowledged it (connector 0.2.22).

deliveryErrorinteger nullable

Outbound only: Apple's non-zero message.error when Messages could not deliver it; the matching draft then has sendError "not_delivered…".

readAtstring date-time nullable
createdAtstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.