nextmail emails

Sends one message now, or holds it for later with --scheduled-at or an undo window with --cancellable-for-seconds. The body comes from exactly one source: html and or text, a stored template, or an existing --draft-id. Naming none is a 422, and template alongside html, text or --draft-id is refused. An immediate send is dispatched inside the request, so the promise usually settles on a sent, partial or failed message. A held send settles as queued or scheduled, so read status rather than treating a resolved promise as delivered mail.

Every call carries an Idempotency-Key. The SDK generates one per call and reuses it on that call's retries, and the API claims it against the key's own unique index before anything is dispatched, so a retried network failure replays the original message instead of sending a second one. Pass --idempotency-key to extend that across processes and restarts, deriving it from what made the send necessary rather than from a clock. A replay resolves with replayed: true and the stored message in its current state. The same key with a different body is a 422 idempotency_key_reuse.

Add translate to deliver the message in the recipient's language. The translation runs when the request is accepted, before any record exists, so a scheduled send carries the approved wording and a translation that cannot be produced refuses the whole send: nothing is ever delivered untranslated as a fallback. By default the subject is translated too and your original text is placed below the translation, captioned in the target language. It works with template, translating what the template rendered, and is refused alongside --draft-id because a draft goes as it was written.

Sends each message in order, as if emails.send had been called for it, and reports per item. It is never all or nothing: a bad address on item 7 fails item 7 and the rest still go, because a batch that rolled back would turn your retry into a guess about which messages had already been delivered. The promise resolves whenever the batch was processed, so check failed and each item's status rather than relying on a throw.

The batch shares one Idempotency-Key, generated once per call or supplied as --idempotency-key, and the server derives a separate key per item from it and the item's position. Retrying the same array replays the items that already went and sends only the ones that did not. Reordering the array between attempts changes which body each position's key is bound to, so an item that moved comes back as an idempotency_key_reuse error.

Apart from a key or scope failure or a server fault, only problems with the batch as a whole reject the promise with a 422: an empty array, more than 100 messages, or more than 10 messages carrying translate. Translation costs several model calls per message and they run one after another, so a larger translated batch would time out partway. Split it, or schedule the messages instead.

Runs the same translation translate performs on a send and stops one step early. The same function produces both, so what comes back is what would go out. Nothing is stored and nothing is sent. Use it when somebody should read the translated wording before it reaches a recipient.

Send the approved result as an ordinary subject and html on emails.send with no translate option. Passing translate again translates a second time, moving the wording off the version that was signed off and discarding any edits. When --include-original is on, html already contains your original text below the translation, so do not append your own copy.

At least one of html, text or subject is required. to accepts a BCP-47 code, an English name or the language's own name, and the response reports the code it settled on in language.code, which is the form worth storing. State from to skip language detection. Otherwise it is detected from the body, and a detector that cannot tell returns null in detectedSourceLanguage rather than guessing.

Scores a message the way a receiving mailbox would, before it goes out: a spam score, a phishing score and an AI-writing score, each 0 to 100, with the signals behind each one. Nothing is stored and nothing is sent.

The same checks score every message that arrives in a mailbox on Nextmail, so what comes back is what a recipient on Nextmail sees in Details. It cannot know a recipient's own filter, sender history or reputation, so a low score is a good sign and not a delivery guarantee.

Run it before an automated send, or as someone writes, and fix what signals names. Sender authentication is taken as passing, since the message will be signed for your domain.

Returns one page of the workspace's send records, ordered newest first. Paging is keyset rather than offset: nextCursor is the id of the last message on the page, and passing it back as cursor continues strictly after it, so messages sent while you page never shift or repeat rows. hasMore is false on the last page and nextCursor is then null.

Filter with status, one value or an array that the SDK joins with commas, with from, which matches the sending address exactly and ignores case, with --broadcast-id, which keeps the copies of one broadcast, and with --scheduled-from and --scheduled-to, which keep the messages scheduled inside a window. An unrecognised status is a 422 invalid_parameter naming the offending values, and a cursor that names no message in the workspace is a 400 invalid_cursor.

Rows are the summary form. They never carry recipients or translation, whose absence on a row says nothing either way, and a tracked message carries only the counts half of tracking: opens, clicks, opened, clicked, openCount, clickCount and firstOpenAt. Call get for per-recipient delivery state and getTracking for the full engagement report.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Returns the full send record for one message: its lifecycle status, delivery attempts and lastError, the schedule fields, and the two parts a list row leaves out. recipients has one entry per address with its own status, error and deliveredAt, and translation records what was done to a translated send.

A message that went out as a single call can still land differently per recipient. status on the message says how the send went as a whole, while each recipient moves on as delivery reports, bounces and complaints arrive. uncertain is a real recipient state: a transport that failed partway cannot say which recipients it reached. suppressed marks an address that previously bounced or complained in this workspace and was held back.

When the message was tracked, tracking carries the full engagement report with per-recipient and per-link detail. When it was not tracked, the field is absent rather than zeroed, because a message with no pixel has no evidence about whether anybody read it.

Returns one page of everything recorded against one send, oldest first. It is the audit behind the current status: when the message was accepted or held, when it was rescheduled or cancelled, when it went out or failed, and every delivery report, bounce, complaint, open, click and file download attributed to it afterwards.

Each event has a dotted type and a data object whose shape depends on it. email.accepted, email.queued and email.scheduled open the trail with the source and recipient count. email.sent names the transport and messageId. email.failed carries the error. email.bounced and email.complained list the affected recipients and whether they were suppressed. email.delivered, email.rescheduled, email.cancelled, email.opened, email.clicked and email.downloaded follow as they happen. email.downloaded counts a person fetching a file that went out as a download link, never a scanner, and carries no recipient: the link is the same for everyone the message went to, so a download cannot be attributed. data is an empty object when an event carries nothing.

Webhooks deliver a subset of these same events as they occur, so this is where to look when a webhook was missed or never subscribed.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Returns the same document tracking.get serves, reached from the msg_ id a sender already holds. It has the message totals, one entry per tracked copy under recipients, and every rewritten link with its clicks under links.

A message that was never tracked is a 404 here rather than an empty report. "We were not recording" and "nobody opened it" are different answers, and a client that renders them the same way makes a claim about a reader on no evidence. Tracking applies per send: opens and clicks record what was applied when the message went out, resolved from the setting of the address it was sent from (its own, else its domain catch-all's when the catch-all caught that address, else off) and any tracking override on the send, not what is switched on now.

Read every count as a floor. An open is inferred from a mail client fetching an image, so a reader whose client blocks images is never counted, and Gmail fetches the image once through its proxy and serves later views from cache. A click is stronger evidence than an open.

Cancels a message that has not been dispatched yet: a send held by scheduledAt, or an immediate send still inside its cancellableForSeconds undo window. The message moves to cancelled, nothing is delivered, and an email.cancelled event is recorded and sent to subscribed webhooks.

Only queued and scheduled messages can be cancelled. Once a message is sending, sent, partial, bounced or failed the call is a 409 email_not_cancellable, since there is no pending dispatch left to stop and mail that has gone cannot be recalled. An immediate send with no undo window is dispatched inside the send request, so by the time you hold its id it is usually past this point.

Cancelling is idempotent. Cancelling an already cancelled message resolves with the same cancelled message rather than an error, and the SDK retries the call after a network failure or a retryable status.

Changes when a message that has not gone yet will be dispatched. scheduledAt is the only thing this call can change, and the SDK sends nothing else: the body, recipients and any translation stay exactly as they were accepted.

The new time takes a Date, an ISO 8601 instant or a duration such as PT30M or P2D, measured from when the server receives the request. It must be at least one second in the future and at most 365 days out, otherwise the call is a 422 on scheduledAt, usually invalid_parameter. Earlier and later times are both allowed.

Only queued and scheduled messages can be moved. Anything already sending, sent, partial, bounced, cancelled or failed is a 409 email_not_cancellable. A queued message inside its undo window can be rescheduled too, which turns it into a scheduled send that stays cancellable until the new time.

Changes a queued or scheduled message before it is dispatched: when it goes with --scheduled-at, what it says with subject, html and text, the address it goes out as with from, and who it goes to with to, cc and bcc. Send any of them together, and a field you leave out keeps its value. This is what editing a scheduled message in the calendar of the app does.

A recipient list replaces the stored one whole, and takes a string such as Ada <[email protected]>, an object with email and name, or an array of either. from is checked as it is on a send, so it has to be an address the key may send as, or the call is a 403 from_address_forbidden.

Only messages that have not gone can change. Anything already sending, sent, partial, bounced, cancelled or failed is a 409 email_not_cancellable. A message translated when it was accepted keeps its approved wording, so a new subject, html or text on it is a 409 translation_locked, and one that was encrypted before it was scheduled keeps its wording and its recipients. Cancel those and send again instead.

Writes the body of an email from prompt, an instruction, a rough draft or a few notes, in the style of the mail this workspace has sent before, as the composer of the app does. subject, to and cc help the greeting and the tone fit, and from, the address it goes out as, has it written as that address.

Give --thread-id to write a reply: the messages of that thread are read as context, which also needs threads:read, and a key limited to particular addresses can only use a thread that arrived at them.

Give draft, the body written so far, and prompt says what to change in it, as the describe bar of the composer does. withSubject: true adds subject to the answer. Give send, the send options as they stand, even {}, and prompt may change the recipients, the send time, tracking, the signature and the language: the answer's send holds only what changed, in the shape emails.send takes, and null takes an option away. Add send.fromOptions, the addresses it may go out as, and prompt may move it to one of them, which the answer names in send.from. Add send.encrypt, whether it is encrypted end to end as it stands, only when every recipient can receive encrypted mail, and prompt may turn encryption on or off. Times such as "tomorrow at 9" are read in --time-zone, or the time zone of the account.

Give templates: true and prompt may switch the email to one of the workspace's published templates, which the answer names in template: pass template: { id: template.id } to emails.send in place of body, because the template's body replaces it. Give template, the id of the template the email uses now, and prompt leaves the body alone. Give files: true and prompt may attach files the workspace holds, found by their name: the answer lists them in attach, each ready to pass to emails.send as { fileId: id } in attachments, and names in attachMissing what matched no file. templates needs templates:read and files needs files:read, and each is ignored without its scope. A key limited to particular addresses only finds the files at those addresses.

Nothing is saved or sent. Pass body to emails.send or drafts.create when it reads right. Each call spends one of the workspace's AI actions, and a workspace that has used them all for the day is refused with a 429 ai_quota_exceeded.

Rewrites a subject or a body and resolves different versions of it, as the rewrite menu of the composer does. action is shorten, lengthen, rephrase, formal, casual or custom, and custom needs instruction to say what to change, or the call is a 422 invalid_parameter on instruction. target is body, the default, or subject, and count asks for 1 to 5 versions, 3 by default.

Give --thread-id when the text is a reply, so the rewrite fits the conversation. That also needs threads:read. The versions never repeat the original and never add facts that are not in it.

Nothing is saved. Each call spends one of the workspace's AI actions.

Reads the body of an email and resolves a short subject for it, under 100 characters, in the style of the mail this workspace has sent, as the subject button of the composer does.

Nothing is saved. Each call spends one of the workspace's AI actions.