POST/emails/send

POST /emails/send

Send a single transactional email, immediately or at a scheduled time.

Request

curl -X POST 'https://api.sendheron.com/api/v1/emails/send' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

emails:send

Body parameters

Name	Type	Required	Description
to	string	Yes	Recipient address.
subject	string	Yes	Subject line.
html	string	Yes	Body as HTML.
from	string	No	Sender address. Defaults to the workspace's default sender identity; with none configured, the send is suppressed with `SENDER_NOT_CONFIGURED`.
fromName	string	No	Display name for this send, shown beside the address and overriding the sender identity's. The address is what domain verification gates, so the name may vary per send: one verified address, several product names. At most 100 characters, with no line breaks and no angle brackets.
replyTo	string	No	Reply-To address.
cc	string[]	No	Up to 50 addresses. Each is checked against the suppression list on its own, because a cc is a real delivery, and a blocked copy is dropped without failing the message.
bcc	string[]	No	Up to 50 addresses, suppression-checked the same way, and a blocked copy is likewise dropped rather than failing the message.
headers	object	No	Custom headers. Headers the platform owns (List-Unsubscribe, authentication, envelope) are rejected rather than quietly dropped.
sendAt	ISO-8601 datetime	No	Schedule the send instead of dispatching it now. Must be in the future. Cancel before it fires with `DELETE /emails/scheduled/{id}`. Cannot be combined with `attachments`.
attachments	object[]	No	At most 10 per message and 10 MB of decoded bytes across all of them together, in the same shape SendGrid takes. Transactional sends only, and this route always qualifies. Cannot be combined with `sendAt`. The nested fields are documented below.
attachments[].content	string	Yes	File content, base64-encoded. The bytes are passed straight to the provider and never stored, and they are deliberately excluded from the idempotency-key payload comparison: a retried job that regenerated the same file (a fresh creation timestamp inside the PDF) replays the original response instead of failing the key with a 409. `filename` and `type` still count towards that comparison.
attachments[].filename	string	Yes	Filename shown to the recipient, e.g. `receipt-1234.pdf`.
attachments[].type	string	Yes	MIME type, from the allowlist: `application/pdf`, `image/png`, `image/jpeg`, `image/gif`, `image/webp`, `text/calendar`, `text/csv`, `text/plain`, `application/zip`. Anything else is refused.
attachments[].disposition	string	No	Only `attachment` is accepted. The field exists for SendGrid payload compatibility; inline (CID) images are not supported.

This route is ALWAYS transactional. It carries no unsubscribe link and a marketing opt-out does not block it, because somebody who left your newsletter still needs their password reset. A verification email at signup is the typical send here. A bounce or a spam complaint blocks it anyway, since that is a deliverability fact rather than a consent one. Do not use it to deliver marketing. A 201 is an outcome, not proof of dispatch: the body is the send record, with status sent, suppressed or queued. A suppressed send names its reason in errorMessage; a queued one is waiting for daily sending capacity, new-sender warm-up or the checks on an old imported list, names why in holdReason, and goes out by itself. Read Send outcomes before writing retry logic: suppressed and queued both mean never retry, and a 503 means retry with the same idempotency key. Messages on this stream carry an open-tracking pixel but their links are never rewritten through click tracking, because a password-reset link must not depend on our redirect being up, so clickCount stays zero here by design. Attachments are pass-through: the bytes go to the provider and are never stored, so deleting a contact leaves no attachment data behind. Compliance is evaluated when a scheduled send fires rather than when you schedule it, so an address suppressed in the meantime is still not mailed.

Responses

Returns 201 on success.

400: The payload failed validation, or the request is not valid for the current state. The body's description names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". The error code is stable and safe to branch on; description is for the human reading the log.
401: Missing or invalid API key.
403: Valid key, but it does not carry the required scope. The error code is apiKeys.insufficientScopes and the description names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404: No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409: A duplicate, or an idempotency key reused with a different payload.
429: Either rate-limit ceiling was exceeded.
400: emailSending.tooManyAttachments, emailSending.attachmentsTooLarge or emailSending.attachmentTypeNotAllowed: an attachment cap or the MIME allowlist was breached. The keys are stable, so branch on them rather than on the text.
400: emailSending.attachmentsNotSchedulable: attachments and sendAt in the same request. Attachment bytes are never stored, so a scheduled send would have nothing left to attach when it fires.
403: subscription.transactionalGraceExhausted: the pooled monthly allowance plus the 10% transactional fair-use grace is spent. Marketing routes stop at the pool itself; this route keeps flowing for another 10% of the pool, then refuses. A lapsed account that has paid before is held to the smallest plan's grace instead of its own, and refuses here when that is spent.
403: subscription.lapsed: the organization has no live subscription and has never paid, as when a trial ends with nothing paid. Only a lapsed account that has paid before keeps a transactional grace, so this route refuses rather than acting as a free sending tier. GET /usage shows it ahead of time: plan.lapsedReason is set and transactionalCeiling is 0.
403: compliance.impersonation: until your account has been reviewed, a sender name or subject that names a well-known brand is refused outright, and no send record is written. It stops applying once the account is approved.
503: emailSending.sendFailed: the provider refused the send. The FAILED attempt is recorded and the idempotency key is released, so retry with the SAME key.
503: emailSending.sendHeld: the send carries attachments and would have had to wait for daily sending capacity, new-sender warm-up or the checks on an old imported list. Attachment bytes are never stored, so it cannot wait. The FAILED attempt is recorded, with the reason it would have waited in errorMessage, and the idempotency key is released, so retry later with the SAME key.

Rate limits

100/min per key, counted against the organization's SEND ceiling (200/min). Both windows are one minute. They limit requests; how much mail goes out in a day is under Daily sending.