Send one email (from an app)

For an app's own server code only: await env.HYPAMOON.sendEmail({ to, subject, text }) does this call, POST env.HYPAMOON_API + "/app-emails" without an Authorization header; Hypamoon adds the app's key, and any other key gets 403 (other keys use POST /emails with messages:write). The same rules as POST /emails, for the app's project: the Mail module on, recipients (to, cc, bcc) that the project knows (a user of the app, a form submission, a document, a chat conversation) or that the owner confirmed, attachments, the daily and per-minute limits per recipient, and the content check. In the app, an attachment's content may be a Uint8Array (like the result of env.HYPAMOON.renderPdf); the wrapper sends it as base64. from is optional: without it the email comes from noreply@ on the project's verified sending domain (the oldest one). No signed-in user is needed, so a scheduled job can send too. With a test key nothing is sent (status simulated).

post/app-emails

Request

Base URL: https://api.hypamoon.com/api/v1
URL: https://api.hypamoon.com/api/v1/app-emails
Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://app.hypamoon.com/oauth/authorize, token URL https://api.hypamoon.com/oauth/token, scopes: data:write)

Headers

Idempotency-Keystring

Optional. The same key returns the same email instead of sending it again.

Request body

fromstring

Optional. An address on a verified sending domain of this project, optionally with a name. Without it: noreply@ on the project's oldest verified sending domain. A project without a verified sending domain sends from Hypamoon's address instead ("<app> via Hypamoon"): to its own team always, to others only category transactional with a payment method or paid plan, up to 50 a day.

ccstring[]

Optional. Copy recipients; they see the to and cc addresses. The same rules as to.

bccstring[]

Optional. Hidden recipients; nobody sees them. The same rules as to.

subjectstring required

The subject line.

textstring

The plain text body. Send text, html or both.

htmlstring

The HTML body. No scripts, no forms; links must show where they go.

reply_tostring

Optional. Where replies go, like the user's own mailbox.

category'transactional' | 'other'

transactional: a reply to something the recipients did (an order, a booking, a form they sent). other (default): anything else; it gets an unsubscribe link with the project's postal address (needs a business address in the company details) and a List-Unsubscribe header, is not sent to people who unsubscribed, and goes to exactly one recipient (use a batch for more people).

in_reply_tostring uuid

The id of the form submission (a document from a public form) or the chat conversation this email answers. Required when the recipient appears in the project only through a form or a chat; the address must be in that submission or conversation.

check_recipientsboolean

Optional, default true: before the first email to an address, check that its domain exists and accepts email, and refuse likely typos (like gmial.com) and, for category other, throwaway addresses. false skips those checks; an address that bounced before is always refused.

idempotency_keystring

Optional. The same key returns the same email instead of sending a second one (also as the Idempotency-Key header).

Response

The same Idempotency-Key as before: the original email, and nothing is sent again.

idstring uuid required

The id of the email. sendEmail and sendEmailBatch in an app return it; getEmail(id) reads it back.

app_idstring uuid nullable required

The app that sent it with env.HYPAMOON.sendEmail; null when it was sent with the API, by an agent or from the portal.

fromstring required

tostring required

The first address in to. All recipients are in recipients.

recipient_countinteger required

to, cc and bcc together; each counts toward the limits and the bundle.

reply_tostring nullable required

subjectstring required

category'transactional' | 'other' required

queued, sent (accepted for delivery), delivered, bounced, complained (marked as spam), failed, or simulated (test mode).

Where the recipient appears in the project.

testboolean required

errorstring nullable required

reasonstring nullable required

Why the email bounced, was marked as spam, is delayed or was not sent, in plain words. null otherwise.

created_atstring required

sent_atstring nullable required

delivered_atstring nullable required

bounced_atstring nullable required

complained_atstring nullable required

sender'hypamoon_fallback'

Only when the project has no verified sending domain of its own: the email went from Hypamoon's address ("<app or project> via Hypamoon"), in a neutral layout without the project's images or design. Tell the user so.

next_stepstring

With sender hypamoon_fallback: how to send from the project's own address with its own design.

Changes

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