Sending mail

POST /messages/send sends a message from one of the account’s addresses:

curl https://api.mailcycle.email/messages/send \
  -H "Authorization: Bearer $MAILCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "receipts-x7k2@example-pool.email",
    "to": "someone@example.com",
    "subject": "Hello",
    "text": "Plain text body"
  }'

{ "sent": true, "messageId": "<…>", "sentCopyId": "msg_…" }

messageId is the Message-ID header the mail went out with. sentCopyId is the copy kept in the address’s Sent folder, which GET /messages/:id takes; it is null for an address with no public key, which keeps no copy.

Field	Notes
from	Required. An address on this account. Any other returns 403 not_your_address.
to	Required. One recipient. An address containing any of < > , ; : " ( ) [ ] \ returns 400 invalid_address.
subject	Required. Up to 998 characters.
text	Required. Up to 200,000 characters.
html	Optional. Up to 200,000 characters.
inReplyTo	Optional. The id of the message this answers.
inReplyToHeader	Optional. That message’s Message-ID, for threading.
fromName	Optional. A display name for the From line, like Support at Acme. One line, up to 78 characters, without quotes, angle brackets or backslashes. Not stored.
attachments	Optional. Up to 10 files; see Attachments.

Who can send depends on how the request is signed in:

Credential	Can send
Session (signed in with the recovery phrase)	On Personal and above.
API key	On Scale and above. Below that, 403 plan_required.
Device credential	On Personal and above, from an address assigned to that device only, up to 20 messages an hour per device.
Agent	On Scale and above, from the addresses assigned to it, within its send mode.

Free receives mail only: every send is 403 plan_required. Every send also counts against the plan’s daily limit; see Rate limits.

The Mailcycle app on a paired device has a compose screen that sends this way, with the device credential: new mail, reply and forward, in plain text with files attached, from the addresses the device holds. A forward includes the original’s attachments.

An address paused after a missed payment returns 403 address_paused. An address on a domain you brought yourself returns 409 domain_not_sending until sending is on for that domain, which usually follows receiving within minutes; check the domain again under Domains.

A reply can name the message it answers. inReplyTo is the Mailcycle message id, and an agent in reply-only mode must send it. inReplyToHeader is the original’s Message-ID, like <id@host>, and threads the reply in the recipient’s mail client.

Sent mail passes through in plain text so the recipient’s server can read it, and is not logged. A copy is filed in the address’s Sent folder, sealed to the address’s public key before it is stored, like received mail, with sentVia saying whether it came from the app, an API key, a device, an agent or a team member. It follows the address’s retention window. See Reading mail.

Attachments

Each file is an object in attachments:

{
  "filename": "invoice.pdf",
  "mimeType": "application/pdf",
  "content": "JVBERi0xLjQK…"
}

Field	Notes
filename	Required. Up to 255 characters, without slashes, backslashes, quotes or control characters.
mimeType	Optional. Defaults to application/octet-stream.
content	Required. The file, base64-encoded.
contentId	Optional. Makes the file an inline image, shown where the html has <img src="cid:…"> with the same id. Letters, digits and . _ @ $ % + = -.

The files can add up to 3.5 MB, and the whole message, once encoded, to 5 MB. Past that the send returns 413 attachments_too_large or 413 message_too_large, and more than 10 files returns 400 too_many_attachments. Nothing is sent. Program and script files (.exe, .bat, .js, .msi, .ps1 and similar) return 400 attachment_blocked. The Sent copy keeps the files, sealed like everything else in it.

Sending is limited to 60 messages an hour per account and 20 per device or agent, three times that on Fleet and five times on Enterprise, and to a daily limit set by the plan; see Rate limits. Mailcycle is not a bulk or marketing sender.