Sending mail

Send a message from a connected account with one outbox request. This page covers single sends. For other jobs, see:

• Drafts: compose in the user's mailbox and send later.
• Mail merge: one personalized message per recipient in one call.
• Templates: stored, reusable content.
• Tracking: open and click tracking, unsubscribe links.
• Suppression lists: who bulk mail must skip.

Send a messageCopy Anchor Link

A send queues an outbox entry for the account and returns 201 at once. The account's provider (Gmail, Microsoft 365 or its SMTP server) sends it in the background.

The key needs the send scope. An account token for that account also works.

curl -X POST "https://api.workwae.com/v1/accounts/$ACCOUNT_ID/outbox" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "to": [{ "name": "Ada Lovelace", "address": "ada@example.com" }],
  "subject": "Your invoice",
  "text": "Hi Ada, your invoice is attached.",
  "html": "<p>Hi Ada, your invoice is attached.</p>",
  "reference": "invoice-1042"
}'

Request fieldsCopy Anchor Link

An unknown field is refused, not ignored. Every refusal and its reason is listed under Send a message in the API reference.

AttachmentsCopy Anchor Link

attachments takes up to 50 objects of { filename, contentType, content }, with content in base64. To show one inline, set its contentId and reference it from the HTML as cid:....

await workwae.outbox.create({
  accountId,
  to: [{ address: "ada@example.com" }],
  subject: "Your invoice",
  html: '<p>Invoice attached.</p><img src="cid:logo">',
  attachments: [
    { filename: "invoice.pdf", contentType: "application/pdf", content: pdfBase64 },
    { filename: "logo.png", contentType: "image/png", content: logoBase64, contentId: "logo" },
  ],
});

Delivery and eventsCopy Anchor Link

The entry's status moves from queued to sending, then ends sent, failed or cancelled. Follow it with webhooks or the change feed. Each event carries the entry's id as outboxId and your reference.

• Delivery is at least once: a retry first looks for a copy that already went out.
• send.failed with code outcome_unknown means the server may have accepted the message but its reply was lost. Workwae does not send it again; decide yourself whether to resend.
• GET /v1/accounts/{accountId}/outbox lists entries newest first (filter with status). GET .../outbox/{outboxId} reads one.
• The sent copy indexed from the account's Sent folder carries the same outboxId.

Full payloads are in the mail events catalog.

Scheduling and undoCopy Anchor Link

• sendAt schedules a send. Omitted or in the past, it goes as soon as possible.
• The account's undoSendSeconds setting (0 to 60) holds every send at least that long.
• While an entry waits, undoUntil says until when cancelling undoes it.

# Move a queued send
curl -X PATCH "https://api.workwae.com/v1/accounts/$ACCOUNT_ID/outbox/$OUTBOX_ID" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "sendAt": "2026-11-02T09:00:00Z" }'

# Cancel (undo) it
curl -X DELETE "https://api.workwae.com/v1/accounts/$ACCOUNT_ID/outbox/$OUTBOX_ID" \
  -H "Authorization: Bearer $WORKWAE_API_KEY"

Send limitsCopy Anchor Link

• The tenant's plan caps the sends it may queue per day (UTC). Past the cap, a send returns 403 plan_limit_sends and a mail merge entry fails with that reason. GET /v1/usage shows the cap (sendsPerDay) and sendsToday.
• A tenant whose payment is past due beyond the grace period is refused new sends with 402 billing_past_due. Sends already queued still go out.

Details are in Daily sends; request rate limits and other plan limits are in Rate limits.