Setting the file. One moment.
Subchapter 4.11
references/inboxes.mdMarkdown27 KBView on GitHub
Detailed flag specifications for resend inboxes commands.
An inbox is an email address at one of your verified domains that sends and
receives email. Receiving must be enabled on the domain, unless the inbox is
created with --forwarding. Received messages are grouped into threads inside
the inbox. Most inbox commands need a full-access API key. A
sending-access key can run threads emails reply, threads emails forward,
drafts create, and drafts send. A key limited to one domain must match the
domain of the inbox. A sending-access key must pass every ID, because the ID
pickers need full access.
The nested commands take their IDs as positional arguments, parent first: the
inbox ID, then the thread, draft, or label ID, then the email ID. Each ID also
has a flag, such as --inbox-id. Pass an ID as an argument or as a flag, not
both, or the command returns invalid_options. The IDs are required in
non-interactive mode. Put the arguments before variadic flags such as --to.
Every command that names an inbox takes its ID or its email address, such as , as or . The address match ignores case. An unknown address returns an error.
support@yourdomain.com[inboxId]--inbox-idCreate a new inbox at one of your verified domains.
| Flag | Type | Required | Description |
|---|---|---|---|
--email-address <address> | string | Yes (non-interactive) | Address for the inbox, e.g. support@yourdomain.com. The part before the @ can contain letters, numbers, and . _ % -, not + |
--name <name> | string | No | Internal name for the inbox, recipients do not see it (max 64 chars) |
--from-name <name> | string | No | Name used when sending from this inbox, e.g. Ada from Support. A plain name, not Name <email> |
--forwarding | boolean | No | Receive mail without an MX record — Resend generates a receiving_address to forward mail to |
The output holds only the inbox ID. Run inboxes get <id> to read the other
fields, such as receiving_address.
Output: {"object":"inbox","id":"<uuid>"}
List all inboxes (default subcommand — resend inboxes alone runs it).
| Flag | Type | Default | Description |
|---|---|---|---|
--limit <n> | number | 10 | Max results, 1-100 |
--after <cursor> | string | — | Forward pagination cursor (an inbox ID) |
--before <cursor> | string | — | Backward pagination cursor (an inbox ID) |
Alias: ls
Output: {"object":"list","has_more":false,"data":[{"id":"<uuid>","name":"<name>"|null,"email_address":"<address>","from_name":"<name>"|null,"unread":0,"last_received":"<date>"|null,"created_at":"<date>","updated_at":"<date>"}]}
Retrieve a single inbox by ID or email address.
Argument: <id> — inbox UUID or inbox email address, e.g. support@yourdomain.com (required in non-interactive mode)
Output: {"object":"inbox","id":"<uuid>","name":"<name>","email_address":"<address>","domain_id":"<uuid>","receiving_address":"<address>"|null,"from_name":"<name>"|null,"unread":0,"drafts":0,"last_received":"<date>"|null,"created_at":"<date>","updated_at":"<date>"}
Update an inbox’s name or from name. At least one option is required. The email address cannot be changed after creation.
Argument: <id> — inbox UUID or email address
| Flag | Type | Description |
|---|---|---|
--name <name> | string | New internal name for the inbox, recipients do not see it (max 64 chars) |
--from-name <name> | string | New name used when sending from this inbox. A plain name, not Name <email>. Pass "" to clear it |
Output: {"object":"inbox","id":"<uuid>"}
List threads in an inbox (default subcommand of resend inboxes threads).
Threads are ordered by newest activity first.
Arguments: [inboxId] (or --inbox-id <id>) — required in non-interactive mode
| Flag | Type | Default | Description |
|---|---|---|---|
--folders <folders...> | string[] | inbox, or inbox, archive, sent with --labels | One or more of inbox, archive, spam, sent, trash |
--labels <label-ids...> | string[] | — | One or more label UUIDs (not names); returns threads with any of them |
--read | boolean | — | Only threads where every email is read; can’t combine with --unread |
--unread | boolean | — | Only threads with at least one unread email; can’t combine with --read |
--limit <n> | number | 10 | Max results, 1-100 |
--after <cursor> | string | — | Forward pagination cursor (a thread ID) |
--before <cursor> | string | — | Backward pagination cursor (a thread ID) |
A thread matches a folder when any of its emails is in it. spam and trash
are only included when you name them.
Alias: ls
Output: {"object":"list","has_more":false,"data":[{"id":"<uuid>","subject":"<subject>"|null,"from":"<sender>"|null,"to":[],"cc":[],"bcc":[],"labels":[],"email_count":1,"has_attachment":false,"has_draft":false,"read":false,"received_at":"<date>","folder":"inbox|archive|spam|sent|trash"}]}
Search threads by text, people, attachments, and dates. Results are ordered by
newest activity first and paginate like threads list. Search can be up to
about a minute behind new emails; use threads list to browse exactly.
Different flags combine, so a thread must match all of them. --folders,
--labels, --read, and --unread apply to the thread; the other filters
must all match the same email in the thread, and that email must itself be in
one of --folders (for sent, an email the inbox sent). When more than 10,000 threads
match, search covers the 10,000 with the newest matching email.
Arguments: [inboxId] (or --inbox-id <id>) — required in non-interactive mode
| Flag | Type | Description |
|---|---|---|
--query <text> | string | Text to find in subject, body, sender, recipients, and attachment names. Every word must match; quote a phrase to match it exactly, prefix a word with - to exclude it. Max 256 characters |
--from <addresses...> | string[] | One or more sender addresses or names, partial match (max 20) |
--to <addresses...> | string[] | Recipients, matched like --from |
--cc <addresses...> | string[] | Cc recipients, matched like --from |
--bcc <addresses...> | string[] | Bcc recipients, matched like --from |
--has-attachment | boolean | Only emails with an attachment; can’t combine with --without-attachment |
--without-attachment | boolean | Only emails without an attachment; can’t combine with --has-attachment |
--start-date <date> | string | Emails sent on or after this date (2026-09-01 or ISO 8601) |
--end-date <date> | string | Emails sent on or before this date; a date covers the whole day |
Also takes --folders, --labels, --read, --unread, --limit, --after,
and --before, same as threads list.
Output: same as threads list, plus "matched_email_id":"<uuid>"|null on
each thread. It is the id of the matching email in threads emails list, so
pass it as the email ID of threads emails get, reply, and forward.
Retrieve a thread’s summary. To read its messages, use
inboxes threads emails list.
Arguments: [inboxId] [threadId] (or --inbox-id <id>, --thread-id <id>) — required in non-interactive mode
Output: {"object":"inbox_thread","id":"<uuid>","subject":"<subject>"|null,"folder":"inbox|archive|spam|sent|trash","labels":[],"read":true}
Mark a thread read/unread or move it. At least one option is required. Moving
a thread out of trash restores it and clears its deletion deadline. To change
the labels of a thread, use threads labels add, set, or remove.
Arguments: [inboxId] [threadId] (or --inbox-id <id>, --thread-id <id>) — required in non-interactive mode
| Flag | Type | Description |
|---|---|---|
--read | boolean | Mark every message in the thread as read |
--unread | boolean | Mark every message in the thread as unread |
--folder <folder> | string | Move to one of inbox, archive, spam, trash (sent is not a valid target) |
Output: {"object":"inbox_thread","id":"<uuid>","subject":"<subject>"|null,"folder":"<folder>","labels":[],"read":true}
Add labels to a thread. Labels already on the thread stay. An unknown label returns an error and changes nothing.
Arguments: [inboxId] [threadId] (or --inbox-id <id>, --thread-id <id>) — required in non-interactive mode
| Flag | Type | Required | Description |
|---|---|---|---|
--labels <label-ids...> | string[] | Yes | 1 to 10 label UUIDs from labels list, comma or space-separated |
Output: {"object":"list","data":[{"id":"<uuid>","name":"<name>","color":"#RRGGBB"}]}, every label on the thread after the change.
Replace every label on a thread in one atomic change. The labels themselves are kept. An unknown label returns an error and changes nothing.
Arguments: [inboxId] [threadId] (or --inbox-id <id>, --thread-id <id>) — required in non-interactive mode
| Flag | Type | Required | Description |
|---|---|---|---|
--labels <label-ids...> | string[] | Yes | 0 to 100 label UUIDs, comma or space-separated. Pass "" to remove every label |
Output: same as threads labels add.
Remove one label from a thread. The label itself is kept. A label that is not on the thread changes nothing.
Arguments: [inboxId] [threadId] [labelId] (or --inbox-id <id>, --thread-id <id>, --label-id <id>) — required in non-interactive mode
Output: same as threads labels add.
threads labels has no list command. Read the labels of a thread with
threads get.
Move a thread to trash and schedule it for deletion in 30 days. This is
reversible. To restore the thread, move it to inbox, archive, or spam
with threads update --folder, which also clears the deletion deadline.
deleted is false when the thread was already in trash.
Arguments: [inboxId] [threadId] (or --inbox-id <id>, --thread-id <id>) — required in non-interactive mode
| Flag | Type | Required | Description |
|---|---|---|---|
--yes | boolean | Yes (non-interactive) | Skip confirmation |
Alias: rm
Output: {"object":"inbox_thread","id":"<uuid>","deleted":true}
List the emails in a thread, oldest first, with their html and text bodies
(default subcommand of resend inboxes threads emails). Use the email id
values with emails get, reply, and forward.
Arguments: [inboxId] [threadId] (or --inbox-id <id>, --thread-id <id>) — required in non-interactive mode
| Flag | Type | Default | Description |
|---|---|---|---|
--limit <n> | number | 10 | Max results, 1-100 |
--after <cursor> | string | — | Forward pagination cursor (an email ID) |
--before <cursor> | string | — | Backward pagination cursor (an email ID) |
Alias: ls
Output: {"object":"list","has_more":false,"data":[{"id":"<uuid>","direction":"inbound|outbound","from":"<sender>","to":[],"cc":[],"bcc":[],"reply_to":[],"subject":"<subject>"|null,"message_id":"<message-id>"|null,"html":"<html>"|null,"text":"<text>"|null,"attachments":[],"read":true,"received_at":"<date>"}]}
Retrieve a single email from a thread.
Arguments: [inboxId] [threadId] [emailId] (or --inbox-id <id>, --thread-id <id>, --email-id <id>) — required in non-interactive mode
Output: {"id":"<uuid>","direction":"inbound|outbound","from":"<sender>","to":[],"cc":[],"bcc":[],"reply_to":[],"subject":"<subject>"|null,"message_id":"<message-id>"|null,"html":"<html>"|null,"text":"<text>"|null,"attachments":[{"id":"<id>","filename":"<name>"|null,"size":123|null}],"read":true,"received_at":"<date>"}
Reply to a specific email in a thread. The reply is sent from the inbox
address. It goes to the author of the original email, or its Reply-To address
if it has one. If the inbox sent the original email, it goes to that email’s
to recipients. The total number of recipients cannot exceed 50, counted after
--reply-all adds everyone. The content of all attachments can total at most
25 MB. A URL file does not count toward the 25 MB, because it is fetched when
the email is sent. An empty file, a blocked file type, or a URL that does not
start with http or that starts with http://localhost: returns an error.
Other URL problems fail the email when it is sent.
Arguments: [inboxId] [threadId] [emailId] (or --inbox-id <id>, --thread-id <id>, --email-id <id>) — required in non-interactive mode; the email ID comes from inboxes threads emails list
| Flag | Type | Required | Description |
|---|---|---|---|
--cc <addresses...> | string[] | No | Cc addresses. Not copied from the original email, except with --reply-all, which merges them without duplicates |
--bcc <addresses...> | string[] | No | Bcc addresses. Not copied from the original email |
--text <text> | string | One of text/html | Plain text reply body |
--html <html> | string | One of text/html | HTML reply body |
--subject <subject> | string | No | Override the reply subject |
--attachment <specs...> | string[] | No | File path or URL to attach, with optional ;cid=, ;type=, ;filename= params, as on emails send. Quote values that contain ; |
--attachments-file <path> | string | No | JSON array of attachment objects (- for stdin) |
--reply-all | boolean | No | Reply to everyone on the original email. For a received email: its Reply-To (or its sender), copying the other To header addresses and its cc. For an email the inbox sent: its Reply-To when it is not the inbox address, otherwise its to, copying its other to addresses and its cc. The inbox address is excluded, duplicates are removed, and Bcc is never copied |
--headers <key=value...> | string[] | No | Custom headers as key=value pairs. In-Reply-To, References, and Reply-To are reserved: Resend sets them, and passing any of them, in any letter case, returns an error. A header name cannot be empty, and names and values cannot contain line breaks or null characters |
--idempotency-key <key> | string | No | Deduplicate request |
Output: {"id":"<email-id>"}, the ID of the sent email. Use it with emails get.
Forward an email to other recipients from the inbox address.
Arguments: [inboxId] [threadId] [emailId] (or --inbox-id <id>, --thread-id <id>, --email-id <id>) — required in non-interactive mode
| Flag | Type | Required | Description |
|---|---|---|---|
--to <addresses...> | string[] | Yes | Recipient addresses |
--cc <addresses...> | string[] | No | Cc addresses |
--bcc <addresses...> | string[] | No | Bcc addresses |
--text <text> | string | No | Plain text note to include |
--html <html> | string | No | HTML note to include |
--subject <subject> | string | No | Override the forwarded subject |
--attachment <specs...> | string[] | No | File path or URL to attach, with optional ;cid=, ;type=, ;filename= params, as on emails send. Quote values that contain ; |
--attachments-file <path> | string | No | JSON array of attachment objects (- for stdin) |
--headers <key=value...> | string[] | No | Custom headers as key=value pairs. In-Reply-To, References, and Reply-To are reserved: Resend sets them, and passing any of them, in any letter case, returns an error. A header name cannot be empty, and names and values cannot contain line breaks or null characters |
--idempotency-key <key> | string | No | Deduplicate request |
--to, --cc, and --bcc combined cannot exceed 50 recipients. The
attachments of the original email are sent with the forward, together with any
files you add. Together they can have at most 25 MB of content. A URL file does
not count toward the 25 MB. An empty file, a blocked file type, or a URL that
does not start with http or that starts with http://localhost: returns an
error. An original attachment
that was sent from a URL cannot be forwarded, and the request returns an error.
Output: {"id":"<email-id>"}, the ID of the sent email. Use it with emails get.
List all labels in an inbox (not paginated; default subcommand of
resend inboxes labels). Use label IDs with threads labels add,
threads labels set, and threads list --labels.
Arguments: [inboxId] (or --inbox-id <id>) — required in non-interactive mode
Alias: ls
Output: {"object":"list","data":[{"id":"<uuid>","name":"<name>","color":"#RRGGBB","created_at":"<date>"}]}
Create a label. An inbox can have up to 100 labels. Label names are unique per inbox, compared without case. The color is stored in uppercase.
Arguments: [inboxId] (or --inbox-id <id>) — required in non-interactive mode
| Flag | Type | Required | Description |
|---|---|---|---|
--name <name> | string | Yes (non-interactive) | Label name, max 64 characters |
--color <color> | string | No | Hex code like '#E93D82', quoted so the shell keeps the # (random when omitted) |
Output: {"object":"inbox_label","id":"<uuid>"}
Update a label’s name or color. At least one option is required.
Arguments: [inboxId] [labelId] (or --inbox-id <id>, --label-id <id>) — required in non-interactive mode
| Flag | Type | Description |
|---|---|---|
--name <name> | string | New label name |
--color <color> | string | New label color as a hex code (same format as create) |
Output: {"object":"inbox_label","id":"<uuid>"}
Delete a label. It is removed from every thread that has it.
Arguments: [inboxId] [labelId] (or --inbox-id <id>, --label-id <id>) — required in non-interactive mode
| Flag | Type | Required | Description |
|---|---|---|---|
--yes | boolean | Yes (non-interactive) | Skip confirmation |
Alias: rm
Output: {"object":"inbox_label","id":"<uuid>","deleted":true}
List drafts in an inbox (default subcommand of resend inboxes drafts).
Arguments: [inboxId] (or --inbox-id <id>) — required in non-interactive mode
| Flag | Type | Default | Description |
|---|---|---|---|
--limit <n> | number | 10 | Max results, 1-100 |
--after <cursor> | string | — | Forward pagination cursor (a draft ID) |
--before <cursor> | string | — | Backward pagination cursor (a draft ID) |
Alias: ls
Output: {"object":"list","has_more":false,"data":[{"id":"<uuid>","type":"standalone|reply","to":["<address>"]|null,"cc":[],"bcc":[],"subject":"<subject>"|null,"snippet":"<text>"|null,"thread_id":"<uuid>"|null,"reply_to_email_id":"<uuid>"|null,"attachments":[{"id":"<uuid>","filename":"<name>","content_type":"<type>","size":123}],"updated_at":"<date>"}]}
Create a standalone draft, or a reply draft when --thread-id and
--reply-to-email-id are passed together. A reply draft without --to is
addressed to the sender of the email it replies to, or to its Reply-To when
set. For an email the inbox sent, it defaults to that email’s to recipients.
At least one content field, attachments included, is required. Combined recipients cannot exceed 50.
Only one unsent reply draft can target an email. A reply draft for an email
that already has one returns the ID of the existing draft. That request ignores
every other flag, except the attachments, which replace the attachments of the
existing draft. A reply draft created without --subject is sent with the
subject of the thread, prefixed with Re: when it does not already start with it.
Arguments: [inboxId] (or --inbox-id <id>) — required in non-interactive mode
| Flag | Type | Description |
|---|---|---|
--to <addresses...> | string[] | Recipient addresses |
--cc <addresses...> | string[] | Cc addresses |
--bcc <addresses...> | string[] | Bcc addresses |
--subject <subject> | string | Draft subject |
--text <text> | string | Plain text body |
--html <html> | string | HTML body |
--thread-id <id> | string | Thread to reply to (pairs with --reply-to-email-id) |
--reply-to-email-id <id> | string | Email the draft replies to (pairs with --thread-id) |
--idempotency-key <key> | string | Deduplicate request |
--attachment <specs...> | string[] | Local file to attach with ;type=<MIME type>, or an http:// or https:// URL, with an optional ;filename=. Quote values that contain ; |
--attachments-file <path> | string | JSON array of objects with either content (base64) plus content_type and filename, or path (an http:// or https:// URL) with an optional filename (- for stdin) |
A URL’s filename defaults to the decoded last segment of its path, and its MIME type
to the type of the downloaded file. The URLs are downloaded when the draft is
saved, so a URL that cannot be downloaded returns an error. A ;cid= returns an
error. The files on a draft can total at most 25 MB, downloads included. An
empty file or a blocked file type, such as .exe, returns an error.
Output: {"object":"inbox_draft","id":"<uuid>"}
Retrieve a draft, including its full body.
Arguments: [inboxId] [draftId] (or --inbox-id <id>, --draft-id <id>) — required in non-interactive mode
Output: {"object":"inbox_draft","id":"<uuid>","type":"standalone|reply","to":["<address>"]|null,"cc":[],"bcc":[],"subject":"<subject>"|null,"html":"<html>"|null,"text":"<text>"|null,"thread_id":"<uuid>"|null,"reply_to_email_id":"<uuid>"|null,"email_id":"<uuid>"|null,"attachments":[{"id":"<uuid>","filename":"<name>","content_type":"<type>","size":123}],"created_at":"<date>","updated_at":"<date>"}
Update a draft’s recipients, subject, or body. At least one option is
required; provided fields replace existing values. Setting --text or
--html replaces the whole body, so the body part you omit becomes null. A
draft that was already sent returns an error. Same flags as drafts create
minus --thread-id, --reply-to-email-id, and --idempotency-key, plus the
clear flags below.
--attachment and --attachments-file replace every attachment on the draft.
--clear-attachments removes them all. Omit all three to keep them.
| Flag | Description |
|---|---|
--clear-to | Sets to to null |
--clear-cc | Sets cc to null |
--clear-bcc | Sets bcc to null |
--clear-subject | Sets subject to null |
--clear-text | Sets text to null. Like --text, it replaces the whole body |
--clear-html | Sets html to null. Like --html, it replaces the whole body |
--clear-attachments | Removes every attachment |
A clear flag and a value for the same field, such as --clear-to with --to,
return invalid_options.
Arguments: [inboxId] [draftId] (or --inbox-id <id>, --draft-id <id>) — required in non-interactive mode
Output: {"object":"inbox_draft","id":"<uuid>"}. Run drafts get to read the draft.
Discard an unsent draft. A draft that was already sent returns an error.
Arguments: [inboxId] [draftId] (or --inbox-id <id>, --draft-id <id>) — required in non-interactive mode
| Flag | Type | Required | Description |
|---|---|---|---|
--yes | boolean | Yes (non-interactive) | Skip confirmation |
Alias: rm
Output: {"object":"inbox_draft","id":"<uuid>","deleted":true}
Send a draft from the inbox address. A reply draft is sent in its thread. A
draft without a thread starts a new thread. The draft must have at least one
to recipient and html or text. A standalone draft also needs a non-empty
subject. A reply draft without a subject is sent with the subject of the thread,
prefixed with Re: when it does not already start with it. A draft that was already sent returns an error.
Arguments: [inboxId] [draftId] (or --inbox-id <id>, --draft-id <id>) — required in non-interactive mode
| Flag | Type | Required | Description |
|---|---|---|---|
--headers <key=value...> | string[] | No | Custom headers as key=value pairs. In-Reply-To, References, and Reply-To are reserved: Resend sets them, and passing any of them, in any letter case, returns an error. A header name cannot be empty, and names and values cannot contain line breaks or null characters |
--idempotency-key <key> | string | No | Deduplicate request |
Output: {"id":"<email-id>"}, the ID of the sent email. Use it with emails get.
Retrieve an inbox’s agent settings (default subcommand of resend inboxes agent).
An inbox without a configured agent returns empty settings.
Arguments: [inboxId] (or --inbox-id <id>) — required in non-interactive mode
Output: {"object":"inbox_agent","instructions":"<text>"|null,"tone":"<tone>"|null,"actions":["draft_reply"]}
tone is a preset key (concise_professional, concise_casual, expanded_professional, expanded_casual) or null. actions lists the actions in a fixed order.
Update an inbox’s agent settings. At least one option is required. Omitted fields keep their current value.
Arguments: [inboxId] (or --inbox-id <id>) — required in non-interactive mode
| Flag | Type | Description |
|---|---|---|
--instructions <text> | string | Instructions the agent follows (max 4000 chars). Pass "" to clear them |
--tone <tone> | string | Tone the agent writes in. One of the presets concise_professional, concise_casual, expanded_professional, expanded_casual. Pass "" to clear it. Other text returns invalid_tone |
--actions <actions...> | string[] | Replaces the whole set (comma or space-separated). Duplicates are removed. One or more of draft_reply, forward_thread, add_labels, assign_thread, mark_as_spam, archive, move_to_trash. Pass "" to disable all actions. Other values return invalid_actions |
Output: {"object":"inbox_agent","id":"<uuid>"}
Delete an inbox. Its threads and messages are removed and the address stops receiving email.
Argument: <id> — inbox UUID or email address
| Flag | Type | Required | Description |
|---|---|---|---|
--yes | boolean | Yes (non-interactive) | Skip confirmation |
Alias: rm
Output: {"object":"inbox","id":"<uuid>","deleted":true}