API

Settings

Every operation in this group: what it accepts, what it returns and the errors it can answer with.

Operations

Mailbox preferences, the signature and tracking of each address, and the brand of the workspace: its images, fonts and sign-in background.

GET`/branding`

Retrieve the brand

settings:readReads

The brand of the workspace, as its Customisations page shows it: a link to each brand image, the primary and secondary fonts, and the background of the sign-in page.

The mark shows in the app's workspace switcher. The logo shows at the top of the sidebar, and it is what brands the web app address, GET /app-host, and, on a paid plan, the emails Nextmail sends for the workspace, which carry it at the top and the foot. Without a logo, the web app address and the emails look like Nextmail. The fonts apply in the web app for everyone in the workspace, the primary font to its text and the secondary font to page headings, and the sign-in background shows on the web app address, either way.

A personal space carries no brand, so its images and fonts read as null and editable is false.

Requires the settings:read scope.

Returns

200Branding

The brand of the workspace.

Errors

The errors every operation can return400401403404422429500Error catalog

Also available in

TypeScript: nextmail.branding.get()
Python: branding.get()
Ruby: branding.get
PHP: branding->get
Go: Branding.Get
Java: branding().get
C#: Branding.GetAsync
CLI: nextmail branding get
MCP: getBranding

PATCH`/branding`

Change the fonts and the sign-in background

settings:writeChanges data

Changes the fonts, the sign-in page background or both, and returns the brand in the same shape as GET /branding. A field left out keeps its value, and so does a font left out of fonts. loginBackground replaces the background there was, and null sets the default.

With kind: "image" the sign-in page shows the photo uploaded with PUT /branding/images/login-background, so upload that first: without it the call is refused. Uploading one switches the page to it on its own.

The brand applies to the whole workspace, so a key or app limited to particular addresses or domains cannot change it.

Requires the settings:write scope.

Request body

fontsobject

The fonts to change. A font left out keeps its value, and null sets the default.

primarystring: The primary font, or null for the default.
Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"
secondarystring: The secondary font, or null for the default.
Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"

loginBackgroundobject

The sign-in page background, replacing the one there was, or null for the default.

Can be null

kindstringRequired: preset shows preset, color fills it with color, and image shows the image uploaded with PUT /branding/images/login-background. image is refused with 422 invalid_parameter until that image is uploaded, and once it is removed the background falls back to the preset or color kept with it, or to null.
One of"preset""color""image"
presetstring: One of the built-in backgrounds. Required when kind is preset.
Can be nullOne of"dusk""mist""sand""night""meadow""dots""brush""trail""ember""canvas""bloom""field""wanderer""gold"
colorstring: A colour as # and six hex digits, such as #1f2937, stored lowercased. Required when kind is color.
Can be nullPattern^#[0-9a-f]{6}$
logostring: Which logo the sign-in page shows: dark, your logo, or light, your logo for dark mode (Nextmail's white logo when you have none). Null picks the one that stands out against the background, and it goes back to null whenever the background changes.
Can be nullOne of"dark""light"

Returns

200Branding

The brand as this call left it.

Errors

400: malformed_json: the body is not valid JSON.
403: insufficient_scope: the key lacks settings:write.
409: branding_unavailable: the workspace is a personal space, which carries no brand.
422: invalid_parameter naming the field, such as fonts.primary for a font that is not on the list, loginBackground.preset when kind is preset and no preset is given, loginBackground.kind when kind is image and no sign-in photo is uploaded, or loginBackground.color for a colour that is not # and six hex digits. unknown_parameter for any other field, and capability_unsupported with param: "domainAllowlist" for a key or app limited to particular addresses or domains.

The errors every operation can return401404429500Error catalog

Also available in

TypeScript: nextmail.branding.update()
Python: branding.update()
Ruby: branding.update
PHP: branding->update
Go: Branding.Update
Java: branding().update
C#: Branding.UpdateAsync
CLI: nextmail branding update
MCP: updateBranding

PUT`/branding/images/{variant}`

Upload a brand image

settings:writeChanges data

Uploads one brand image, replacing the one there was, and returns the brand. Send the image itself as the body, not JSON, with its type in Content-Type. Up to 5 MB goes in. variant names the image:

- mark: the square mark. image/svg+xml, image/png, image/jpeg, image/webp, fitted into 512 by 512 pixels and stored as WebP. - wordmark: the logo. image/svg+xml, image/png, image/jpeg, image/webp, fitted into 1024 by 256 pixels and stored as WebP. - wordmark-dark: the logo for dark mode, shown in place of the logo when the app is dark. image/svg+xml, image/png, image/jpeg, image/webp, fitted into 1024 by 256 pixels and stored as WebP. - login-background: the photo behind the sign-in page of the web app address. image/png, image/jpeg, image/webp, image/gif, fitted into 2560 by 1600 pixels and stored as WebP. Uploading it also switches the sign-in page to it.

An SVG is turned into a picture, and an animated image keeps its first frame.

The brand applies to the whole workspace, so a key or app limited to particular addresses or domains cannot change it.

Requires the settings:write scope.

Path parameters

variantstringRequired: Which image: mark, the square icon, wordmark, the logo, wordmark-dark, the logo for dark mode, or login-background, the photo behind the sign-in page.
One of"mark""wordmark""wordmark-dark""login-background"

Request body

Content typeimage/webp, image/png, image/jpeg, image/gif, image/svg+xml

binary

Returns

200Branding

The brand, with the new image.

Errors

403: insufficient_scope: the key lacks settings:write.
409: branding_unavailable: the workspace is a personal space, which carries no brand.
422: invalid_image when the body is not an image of a type that variant accepts, is too large or cannot be read. invalid_parameter on variant for a name that is not one of the four, and capability_unsupported with param: "domainAllowlist" for a key or app limited to particular addresses or domains.
502: image_not_stored: the image was read but could not be stored. Try again.
503: image_busy: the image service is saturated. Try again shortly.

The errors every operation can return400401404429500Error catalog

Also available in

TypeScript: nextmail.branding.uploadImage()
Python: branding.upload_image()
Ruby: branding.upload_image
PHP: branding->uploadImage
Go: Branding.UploadImage
Java: branding().uploadImage
C#: Branding.UploadImageAsync
CLI: nextmail branding upload-image
MCP: setBrandImage

DELETE`/branding/images/{variant}`

Remove a brand image

settings:writeDeletes

Removes one brand image, deletes the stored file and returns the brand, so the default shows in its place. Removing the sign-in photo while the sign-in page shows it switches the page back to the preset or colour chosen before it, or to the default. Removing an image that is not set changes nothing, so a repeated call is safe.

The brand applies to the whole workspace, so a key or app limited to particular addresses or domains cannot change it.

Requires the settings:write scope.

Path parameters

variantstringRequired: Which image: mark, the square icon, wordmark, the logo, wordmark-dark, the logo for dark mode, or login-background, the photo behind the sign-in page.
One of"mark""wordmark""wordmark-dark""login-background"

Returns

200Branding

The brand, without that image.

Errors

403: insufficient_scope: the key lacks settings:write.
409: branding_unavailable: the workspace is a personal space, which carries no brand.
422: invalid_parameter on variant for a name that is not one of the four, and capability_unsupported with param: "domainAllowlist" for a key or app limited to particular addresses or domains.

The errors every operation can return400401404429500Error catalog

Also available in

TypeScript: nextmail.branding.removeImage()
Python: branding.remove_image()
Ruby: branding.remove_image
PHP: branding->removeImage
Go: Branding.RemoveImage
Java: branding().removeImage
C#: Branding.RemoveImageAsync
CLI: nextmail branding remove-image
MCP: removeBrandImage

GET`/settings`

Read mailbox settings

settings:readReads

Every field with defaults filled in, so reading a setting never requires knowing which release introduced it.

Without address this is your account and the workspace. The account fields are the caller's own: for an API key the workspace owner's, for a connected app the person who connected it. The privacy fields and workspaceName are the workspace's. signature, openEmailSignature, trackOpens and trackClicks belong to each address and read as the built-in defaults here: no signature, the Nextmail footer on, and open and link tracking off.

With address, the fields as they apply to that scope. For one address the four per-address fields resolve the way a send from it does: the address's own values, then its domain's catch-all when the catch-all caught that address rather than it being one you created, then the built-in defaults, and a plus address with no settings of its own reads its base address's. externalImages, trustedSenders and the blocklist resolve from the workspace, then the domain, then the catch-all, then the base of a plus address, then the address itself, and the last of them that sets a field wins. *@domain reads a catch-all the same way, and @domain reads the workspace's privacy with the domain's own on top. Every other field reads the same whatever the scope.

overrides holds what the scope sets itself, and everything not in it is inherited. address in the response is the scope the call named, lowercased, or null.

Requires the settings:read scope.

Query parameters

addressstring: The scope to read or change: one address such as hello@example.com, *@example.com for the catch-all of that domain, or @example.com for the whole domain. An address or a catch-all keeps its own signature, openEmailSignature, trackOpens, trackClicks, externalImages, trustedSenders and blocklist, and a domain its own externalImages, trustedSenders and blocklist. On a read any address resolves the way mail to and from it does. On a write it has to be an address in this workspace, a catch-all on a verified domain here with its catch-all on, or a domain in this workspace. A key narrowed to particular addresses or domains may name only an address it holds, and a catch-all or a domain only when it holds that domain whole, or it is 422 capability_unsupported.
Up to 320 characters

Returns

200Settings

Settings.

Errors

422: invalid_parameter on address when it is not one address, *@domain or @domain, or capability_unsupported when a narrowed key names an address or a domain it does not hold.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript: nextmail.settings.get()
Python: settings.get()
Ruby: settings.get
PHP: settings->get
Go: Settings.Get
Java: settings().get
C#: Settings.GetAsync
CLI: nextmail settings get
MCP: getSettings

PATCH`/settings`

Change mailbox settings

settings:writeChanges data

A partial update: a field you omit keeps its value, and a list replaces the old one.

Without address, this changes your account and the workspace. The account fields (time zone and formats, theme, sounds, notifications and the rest) are saved on the caller's account: for an API key the workspace owner's, for a connected app the person who connected it. workspaceName renames the workspace. The privacy fields (externalImages, trustedSenders, blockedSenders, blockedDomains, blockedWords, useDefaultBlockedWords, semanticSearch, replySuggestions, knowledgeLearning) and the marketing footer fields (marketingSenderName, marketingPostalAddress) are saved on the workspace, and null removes the workspace's own value so the default applies again. A key narrowed to particular addresses or domains may change none of those workspace fields or the name, and gets 422 capability_unsupported. signature, openEmailSignature, trackOpens and trackClicks are refused without address with 422 address_required naming the field, because they are set on each address, and nothing is written. semanticSearch: false turns search by meaning off for the whole workspace: its mail stops going to the embedding model, what was stored for it is deleted at once, and semantic on GET /threads runs a text search until it is turned back on, when the mail is read for meaning again over the next minutes. replySuggestions: false stops suggested replies for the whole workspace: no thread goes to a model for them any more, what was stored is deleted at once, and GET /threads/{id}/reply-suggestions answers none until it is turned back on.

With address, the body gives that scope a choice of its own. One address or a catch-all (*@domain) takes signature, openEmailSignature, trackOpens, trackClicks, externalImages, trustedSenders, blockedSenders, blockedDomains, blockedWords and useDefaultBlockedWords, and a whole domain (@domain) the last six only. null removes the scope's own value, so it inherits again from the scope above it. Any other field is 422 not_per_address naming it, semanticSearch, replySuggestions, knowledgeLearning and the marketing footer fields included, since they belong to the whole workspace. The scope has to be an address in this workspace, a catch-all on a verified domain here with its catch-all on, or a domain in this workspace, or it is 422 invalid_parameter on address. The response is what GET /settings?address= returns for it. A catch-all's values apply to the addresses its domain catches, and a new address created on that domain starts with a copy of them and changes on its own from then on.

Returns the SAVED state, so the signature you get back is the sanitised one that will actually be sent rather than what you asked for.

Requires the settings:write scope.

Query parameters

addressstring: The scope to read or change: one address such as hello@example.com, *@example.com for the catch-all of that domain, or @example.com for the whole domain. An address or a catch-all keeps its own signature, openEmailSignature, trackOpens, trackClicks, externalImages, trustedSenders and blocklist, and a domain its own externalImages, trustedSenders and blocklist. On a read any address resolves the way mail to and from it does. On a write it has to be an address in this workspace, a catch-all on a verified domain here with its catch-all on, or a domain in this workspace. A key narrowed to particular addresses or domains may name only an address it holds, and a catch-all or a domain only when it holds that domain whole, or it is 422 capability_unsupported.
Up to 320 characters

Request body

timezonestring: IANA time zone such as Europe/Berlin. Saved on the account.
timeFormatstring: 12h or 24h, how the app writes times. Saved on the account.
One of"12h""24h"
dateFormatstring: dmy, mdy or ymd, the order the app writes dates in. Saved on the account.
One of"dmy""mdy""ymd"
weekStartstring: monday or sunday, the first day of the week in the calendar and date pickers. Saved on the account.
One of"monday""sunday"
workspaceNamestring: Renames this workspace, 1 to 64 characters once trimmed. A personal space has no name of its own, so it is 422 invalid_parameter there. Not with address.
externalImagesboolean: Loads pictures in mail automatically. Off means senders cannot tell you read it. On by default. Without address it is the workspace's choice, and with an address, a catch-all or @domain that scope's own. null removes the value the scope sets itself, so it inherits again.
Can be null
semanticSearchboolean: Search by meaning for the whole workspace. On by default. false stops its mail going to the embedding model, deletes what was stored and makes semantic run a text search, and null turns it back on. Not with address.
Can be null
replySuggestionsboolean: Suggested replies for the whole workspace. On by default. false stops threads going to a model for them and deletes the suggestions that were stored, and null turns them back on. Not with address.
Can be null
knowledgeLearningboolean: Knowledge base suggestions for the whole workspace. On by default: the AI reads the replies sent in a conversation and the questions nothing answered, and suggests notes from them, and it checks closely related items for conflicts. false stops all three, and null turns them back on. Suggestions already made stay until they are accepted or dismissed. Not with address.
Can be null
trustedSendersstring[]: Senders whose pictures always load while externalImages is off. Replaces the whole list. Without address it is the workspace's list, and with an address, a catch-all or @domain that scope's own. null removes the scope's own list, so it inherits again.
Can be null
colorThemestring: light, dark or system, the app's theme. Saved on the account.
One of"light""dark""system"
openEmailSignatureboolean: Adds the Nextmail footer to mail from the address named by address while it has no signature. On by default. null removes the address's own value. Only with an address or a catch-all.
Can be null
signaturestring: HTML of the default signature of the address named by address, the one new mail from it carries, at most 150,000 characters before and after sanitising. Sanitised on write. An address keeps a list of signatures, which GET /signatures returns, and this field is the one that is the default for new mail. Writing it rewrites that signature, or adds one called Signature and makes it the default when the address has none. An empty string or null leaves new mail from the address with no signature, and replies too when they used the same one, and deletes nothing. Only with an address or a catch-all.
Can be nullUp to 150000 characters
defaultEmailAliasstring: The address the composer starts from when you write new mail in the app. Saved on the account.
undoSendEnabledboolean: Holds each send from the app for 30 seconds so it can be cancelled. Off by default. Saved on the account.
trackOpensboolean: Open tracking on mail from the address named by address, for a send that does not set tracking.opens. Off by default. null removes the address's own value. Only with an address or a catch-all.
Can be null
trackClicksboolean: Link tracking on mail from the address named by address, for a send that does not set tracking.clicks. Off by default. null removes the address's own value. Only with an address or a catch-all.
Can be null
imageCompressionstring: low, medium or original, how far pictures attached in the app are compressed before they are sent. Saved on the account.
One of"low""medium""original"
attachmentDeliverystring: How files go out on a send that does not set attachmentDelivery itself: mime attaches them to the message, link sends download links, and auto links large files only, which needs a files address. Saved on the account.
One of"mime""link""auto"
autoReadboolean: Marks mail read when you open it in the app. Saved on the account.
aiWrittenLabelboolean: Shows the AI-written label on mail whose words look generated. Mail is scored either way and the sender is never told. Saved on the account.
animationsboolean: Motion in the app. Off makes everything appear at once. Saved on the account.
desktopNewMailboolean: A desktop notification when a message reaches the inbox while the app is open in a browser that allows them. Saved on the account.
desktopOnlyWhenHiddenboolean: Desktop notifications only while the tab is hidden, so they stay quiet while you watch the inbox. Saved on the account.
phoneNewMailboolean: A push to your phones when a message reaches the inbox. Saved on the account.
phoneRepliesboolean: A push to your phones when someone answers your mail. Saved on the account.
phoneScheduledSendboolean: A push to your phones when a scheduled message goes out. Saved on the account.
phoneFollowUpsboolean: A push to your phones when a message you asked to be reminded about has had no reply by then. Saved on the account.
inboxTabsboolean: Shows the inbox as tabs: Primary, Promotions, Updates, Social and Forums. Mail is sorted either way, and turning this on sorts the last 1,000 inbox threads of the open workspace. Saved on the account.
primaryOnlyAlertsboolean: With inbox tabs on, pushes, sounds and desktop notifications fire only for mail sorted into Primary. Saved on the account.
phoneSendFailuresboolean: A push to your phones when a message fails to send. Saved on the account.
phonePreviewsboolean: Shows what a message says in its push. Off sends pushes without the content. Saved on the account.
phoneSoundboolean: Plays a sound with each push. Off makes them silent. Saved on the account.
phoneMutedWorkspacesstring[]: Workspace ids whose mail sends no push to your phones. Replaces the whole list. PUT /account/notifications/push/{workspaceId} changes one workspace at a time. Saved on the account.
Up to 200 items
soundNewMailboolean: Chimes when mail arrives while the app is open. Saved on the account.
soundAiDoneboolean: Chimes when the assistant finishes a reply. Saved on the account.
soundSentboolean: Chimes when your message goes out. Saved on the account.
blockedSendersstring[]: Senders whose mail is refused on arrival, plus-tags included. Mail already delivered stays. Replaces the whole list. Without address it is the workspace's list, and with an address, a catch-all or @domain that scope's own. null removes the scope's own list, so it inherits again.
Can be null
blockedDomainsstring[]: Domains whose mail is refused on arrival, subdomains included. Replaces the whole list. Without address it is the workspace's list, and with an address, a catch-all or @domain that scope's own. null removes the scope's own list, so it inherits again.
Can be null
blockedWordsstring[]: Words that open matching mail behind a warning. Nothing is deleted. Replaces the whole list. Without address it is the workspace's list, and with an address, a catch-all or @domain that scope's own. null removes the scope's own list, so it inherits again.
Can be null
useDefaultBlockedWordsboolean: Adds the built-in list of English profanities and slurs to blockedWords. Off by default. Without address it is the workspace's choice, and with an address, a catch-all or @domain that scope's own. null removes the scope's own value, so it inherits again.
Can be null
translateLanguagestring: The language Translate offers first, a language code such as de. Empty means English. Saved on the account.
translateRepliesboolean: Opens replies on threads you translated already translated into your language. Saved on the account.
showAvatarToContactsboolean: Shows your profile photo to Nextmail users on your address. Saved on the account.
lookupContactPhotosboolean: Fetches missing photos of the people you email from Gravatar and company logos. Saved on the account.
marketingSenderNamestring: Who the footer of broadcasts and automation emails names as the sender, one line of at most 120 characters, shown above marketingPostalAddress. Empty, the default, uses the workspace name. null empties it. Not with address.
Can be nullUp to 120 charactersPattern^[^\u0000-\u001F\u007F]*$
marketingPostalAddressstring: The postal address the footer of broadcasts and automation emails shows, at most 500 characters on one line or several, which many countries require of marketing email. The footer is the one Nextmail adds to a message that does not place {{unsubscribeUrl}} itself, written in English. Empty, the default, shows no address. null empties it. Not with address.
Can be nullUp to 500 charactersPattern^[^\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]*$

Returns

200Settings

The saved settings.

Errors

422: Rejected: address_required (a per-address field sent without address), not_per_address (a field the scope address names does not keep), signature_too_long, blocklist_entry_too_broad, invalid_parameter (including null for a field that cannot be cleared, and workspaceName on a personal space), or capability_unsupported when a narrowed key names an address or a domain it does not hold, or changes a workspace field.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript: nextmail.settings.update()
Python: settings.update()
Ruby: settings.update
PHP: settings->update
Go: Settings.Update
Java: settings().update
C#: Settings.UpdateAsync
CLI: nextmail settings update
MCP: updateSettings

GET`/out-of-office`

Read out of office replies

settings:readReads

Every out of office reply saved in the workspace, by address. With address the list holds exactly one row, the reply of that address, which reads enabled: false with empty text when none was ever saved. active says whether the reply is going out right now: it is on, the start has passed and the end has not.

Requires the settings:read scope.

Query parameters

addressstring: One address, such as hello@example.com, or *@example.com for the catch-all of a domain. A key or an app limited to particular addresses or domains reaches only the addresses it holds, and a catch-all only when it holds the domain whole.
Up to 320 characters

Returns

200OutOfOfficeList

The replies, by address.

Errors

The errors every operation can return400401403404422429500Error catalog

Also available in

TypeScript: nextmail.outOfOffice.list()
Python: out_of_office.list()
Ruby: out_of_office.list
PHP: outOfOffice->list
Go: OutOfOffice.List
Java: outOfOffice().list
C#: OutOfOffice.ListAsync
CLI: nextmail out-of-office list
MCP: getOutOfOffice

PUT`/out-of-office`

Set an out of office reply

settings:writeChanges data

Saves the out of office reply of one address, or of a catch-all with *@example.com, replacing whatever was saved. While it is active, each person who writes to the address gets the message once for the whole away period, as a reply in the same thread. Mail that would not alert anyone gets no reply: spam, mail a rule filed away, newsletters and other bulk mail, automatic mail, bounces, blocked senders and the workspace's own addresses. With contactsOnly, only people in the contacts, or people the workspace has written to, are answered.

Leave startsAt out to start now, or to keep the start of a reply that is already on, and endsAt out or null to keep it on until it is switched off. An address with a reply of its own is never answered by the catch-all. Replies count toward the monthly sends, carry no tracking, and still go out on muted threads.

Requires the settings:write scope.

Query parameters

addressstringRequired: One address, such as hello@example.com, or *@example.com for the catch-all of a domain. A key or an app limited to particular addresses or domains reaches only the addresses it holds, and a catch-all only when it holds the domain whole.
Up to 320 characters

Request body

enabledboolean: Whether the reply is switched on. Left out, true. false keeps the text and pauses the reply.
Defaulttrue
startsAtstring: When the reply starts. Left out or null, now, or the start it already has while the reply is on.
Can be nullFormatdate-time
endsAtstring: When it stops, later than startsAt. Left out or null, it stays on until it is switched off.
Can be nullFormatdate-time
subjectstring: The subject of the reply, at most 255 characters. Left out or empty, the reply answers with Re: and the subject received.
Up to 255 charactersDefault""
messagestringRequired: The reply, as plain text, 1 to 10,000 characters once trimmed. Line breaks are kept.
1 to 10000 characters
contactsOnlyboolean: Answer only contacts and people the workspace has written to. Left out, false.
Defaultfalse

Returns

200OutOfOffice

Saved, read back as it is stored.

Errors

422: invalid_parameter: address is missing, is not an address of the workspace or names a whole domain, the message is empty, or endsAt is not after startsAt or is already in the past. capability_unsupported: the key or app does not hold that address.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript: nextmail.outOfOffice.set()
Python: out_of_office.set()
Ruby: out_of_office.set
PHP: outOfOffice->set
Go: OutOfOffice.Set
Java: outOfOffice().set
C#: OutOfOffice.SetAsync
CLI: nextmail out-of-office set
MCP: setOutOfOffice

DELETE`/out-of-office`

Remove an out of office reply

settings:writeDeletes

Removes the saved reply of one address or catch-all, so nothing is answered from it any more. Removing a reply that was never saved changes nothing. To pause a reply and keep its text, save it with enabled: false instead.

Requires the settings:write scope.

Query parameters

addressstringRequired: One address, such as hello@example.com, or *@example.com for the catch-all of a domain. A key or an app limited to particular addresses or domains reaches only the addresses it holds, and a catch-all only when it holds the domain whole.
Up to 320 characters

Returns

200DeletedOutOfOffice

Removed.

Errors

The errors every operation can return400401403404422429500Error catalog

Also available in

TypeScript: nextmail.outOfOffice.clear()
Python: out_of_office.clear()
Ruby: out_of_office.clear
PHP: outOfOffice->clear
Go: OutOfOffice.Clear
Java: outOfOffice().clear
C#: OutOfOffice.ClearAsync
CLI: nextmail out-of-office clear
MCP: clearOutOfOffice

GET`/signatures`

List signatures

settings:readReads

Every signature in the workspace, by address and then oldest first, or the signatures of one address with address. An address keeps a list of named signatures, as the Signature tab of an address shows it. At most one is the default for new mail (isDefault) and at most one the default for replies and forwards (isReplyDefault), and they can be the same one. A key or an app limited to particular addresses or domains reaches only the signatures of the addresses it holds, and those of a catch-all only when it holds the domain whole.

Requires the settings:read scope.

Query parameters

addressstring: One address, such as hello@example.com, or *@example.com for the catch-all of a domain. Left out, the list holds every address.
Up to 320 characters
limitinteger: Rows per page, 1 to 100.
At least 1At most 100Default25
cursorstring: The previous page's nextCursor, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 invalid_cursor.

Returns

200SignatureList

A page of signatures.

Errors

422: invalid_parameter: address is not an address or names a whole domain. capability_unsupported: the key or app does not hold that address.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript: nextmail.signatures.list()nextmail.signatures.listAll()nextmail.signatures.iterate()
Python: signatures.list()signatures.list_all()signatures.iterate()
Ruby: signatures.listsignatures.list_allsignatures.iterate
PHP: signatures->listsignatures->listAllsignatures->iterate
Go: Signatures.ListSignatures.ListAllSignatures.Iterate
Java: signatures().listsignatures().listAllsignatures().iterate
C#: Signatures.ListAsyncSignatures.ListAllAsyncSignatures.IterateAsync
CLI: nextmail signatures list
MCP: listSignatures

POST`/signatures`

Create a signature

settings:writeChanges data

Adds a signature to one address, or to a catch-all with *@example.com. The HTML is sanitised on write, as outgoing mail is. The first signature of an address becomes its default for new mail and for replies unless isDefault or isReplyDefault says otherwise, and a later one becomes a default only when asked. Making one the default takes that place from the signature that held it. An address holds at most 50 signatures.

Requires the settings:write scope.

Request body

addressstringRequired: The address the signature is for, such as hello@example.com, or *@example.com for the catch-all of a domain.
3 to 320 characters
namestringRequired: What the signature is called. Unique on its address, whatever the case.
1 to 80 characters
htmlstringRequired: The signature as HTML. It is sanitised on write and has to keep some text or an image.
1 to 150000 characters
isDefaultboolean: true makes it the signature of new mail from the address. false takes that away when it held it.
isReplyDefaultboolean: true makes it the signature of replies and forwards from the address. false takes that away when it held it.

Returns

201Signature

The signature, read back as it is stored.

Errors

409: signature_name_taken: the address already has a signature with that name.
422: invalid_parameter: a field is missing or malformed, address is not an address of the workspace or names a whole domain, or the signature is empty once it is cleaned up. signature_too_long: it is too long before or after cleaning. signature_limit_reached: the address is full. capability_unsupported: the key or app does not hold that address.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript: nextmail.signatures.create()
Python: signatures.create()
Ruby: signatures.create
PHP: signatures->create
Go: Signatures.Create
Java: signatures().create
C#: Signatures.CreateAsync
CLI: nextmail signatures create
MCP: createSignature

GET`/signatures/{id}`

Read a signature

settings:readReads

One signature by its id. A key or an app limited to particular addresses or domains reaches only the signatures of the addresses it holds, and those of a catch-all only when it holds the domain whole.

Requires the settings:read scope.

Path parameters

idstringRequired: The signature, as GET /signatures returns it.

Returns

200Signature

The signature.

Errors

The errors every operation can return400401403404422429500Error catalog

Also available in

TypeScript: nextmail.signatures.get()
Python: signatures.get()
Ruby: signatures.get
PHP: signatures->get
Go: Signatures.Get
Java: signatures().get
C#: Signatures.GetAsync
CLI: nextmail signatures get
MCP: listSignatures

PATCH`/signatures/{id}`

Update a signature

settings:writeChanges data

Renames a signature, rewrites its HTML, or changes what it is the default for. Send only what changes. isDefault: true makes it the default for new mail in place of the one that was, and isDefault: false leaves new mail from the address with no signature when this one was the default. isReplyDefault does the same for replies and forwards. A message that is already scheduled picks up the new HTML when it goes out.

Requires the settings:write scope.

Path parameters

idstringRequired: The signature, as GET /signatures returns it.

Request body

namestring: What the signature is called. Unique on its address, whatever the case.
1 to 80 characters
htmlstring: The signature as HTML. It is sanitised on write and has to keep some text or an image.
1 to 150000 characters
isDefaultboolean: true makes it the signature of new mail from the address. false takes that away when it held it.
isReplyDefaultboolean: true makes it the signature of replies and forwards from the address. false takes that away when it held it.

Returns

200Signature

The signature after the change.

Errors

409: signature_name_taken: the address already has a signature with that name.
422: invalid_parameter: nothing to change was sent, a field is malformed, or the signature is empty once it is cleaned up. signature_too_long: it is too long before or after cleaning. capability_unsupported: the key or app does not hold the address the signature belongs to.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript: nextmail.signatures.update()
Python: signatures.update()
Ruby: signatures.update
PHP: signatures->update
Go: Signatures.Update
Java: signatures().update
C#: Signatures.UpdateAsync
CLI: nextmail signatures update
MCP: updateSignature

DELETE`/signatures/{id}`

Delete a signature

settings:writeDeletes

Deletes a signature for good. When it was a default, that default is left empty, so mail it would have signed goes out with no signature until another one is chosen. A scheduled message that named it with signatureId carries the default of its address instead.

Requires the settings:write scope.

Path parameters

idstringRequired: The signature, as GET /signatures returns it.

Returns

200DeletedSignature

Deleted.

Errors

The errors every operation can return400401403404422429500Error catalog

Also available in

TypeScript: nextmail.signatures.delete()
Python: signatures.delete()
Ruby: signatures.delete
PHP: signatures->delete
Go: Signatures.Delete
Java: signatures().delete
C#: Signatures.DeleteAsync
CLI: nextmail signatures delete
MCP: deleteSignature

POST`/signatures/{id}/copy`

Copy a signature to other addresses

settings:writeChanges data

Puts a copy of a signature on up to 500 other addresses or catch-alls, as Copy to other addresses does in the app. An address that already has a signature with the same name gets its HTML replaced, so copying again after an edit brings every copy up to date, and any other address gets a new signature. A copy becomes a default where isDefault or isReplyDefault says so, and on an address that had no signature at all. The address the signature is already on is skipped. Each copy is its own signature from then on.

Requires the settings:write scope.

Path parameters

idstringRequired: The signature, as GET /signatures returns it.

Request body

addressesstring[]Required: The addresses to copy it to. Each is one address or *@example.com for a catch-all.
1 to 500 items
isDefaultboolean: true makes it the signature of new mail from the address. false takes that away when it held it.
isReplyDefaultboolean: true makes it the signature of replies and forwards from the address. false takes that away when it held it.

Returns

200SignatureCopyList

The copies, one for each address.

Errors

422: invalid_parameter: addresses is empty or too long, or one of them is not an address of the workspace or names a whole domain. signature_limit_reached: one of the addresses is full, and the addresses before it already have their copy. capability_unsupported: the key or app does not hold one of the addresses.

The errors every operation can return400401403404429500Error catalog

Also available in

TypeScript: nextmail.signatures.copy()
Python: signatures.copy()
Ruby: signatures.copy
PHP: signatures->copy
Go: Signatures.Copy
Java: signatures().copy
C#: Signatures.CopyAsync
CLI: nextmail signatures copy
MCP: copySignature

Objects

`Branding`object

The brand of the workspace: its images, its fonts and the background of its sign-in page. The logo is what brands the web app address, GET /app-host, and, on a paid plan, the emails Nextmail sends for the workspace; without one both look like Nextmail. The fonts apply in the web app for everyone in the workspace, the primary font to its text and the secondary font to page headings, and the sign-in background shows on the web app address, whether or not a logo is set. A personal space carries no brand, so every image and font is null there.

objectstring

One of"branding"

editableboolean

Whether this key may change the brand: false in a personal space, without settings:write, or for a key limited to particular addresses or domains.

imagesobject

A link to each brand image, or null when it is not set.

markstring: The square mark, or null.
Can be null
wordmarkstring: The logo, or null.
Can be null
wordmarkDarkstring: The logo for dark mode, or null. Without it the logo shows in dark mode too.
Can be null
loginBackgroundstring: The photo behind the sign-in page, or null.
Can be null

fontsobject

The two fonts of the brand, each a font id from the supported list or null for the default.

primarystring: The primary font, or null for the default.
Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"
secondarystring: The secondary font, or null for the default.
Can be nullOne of"system""arial""helvetica""verdana""tahoma""trebuchet-ms""georgia""times-new-roman""courier-new""dm-sans""inter""roboto""open-sans""lato""montserrat""poppins""nunito""work-sans""source-sans-3""ibm-plex-sans""merriweather""playfair-display""instrument-serif""jetbrains-mono""dm-mono""geist-mono"

loginBackgroundobject

What the sign-in page of the web app address shows behind the form, or null for the default. kind picks one of three: a preset, a color or the uploaded image. The value for the other kinds may be kept, so switching back restores it.

Can be null

kindstringRequired: preset shows preset, color fills it with color, and image shows the image uploaded with PUT /branding/images/login-background. image is refused with 422 invalid_parameter until that image is uploaded, and once it is removed the background falls back to the preset or color kept with it, or to null.
One of"preset""color""image"
presetstring: One of the built-in backgrounds. Required when kind is preset.
Can be nullOne of"dusk""mist""sand""night""meadow""dots""brush""trail""ember""canvas""bloom""field""wanderer""gold"
colorstring: A colour as # and six hex digits, such as #1f2937, stored lowercased. Required when kind is color.
Can be nullPattern^#[0-9a-f]{6}$
logostring: Which logo the sign-in page shows: dark, your logo, or light, your logo for dark mode (Nextmail's white logo when you have none). Null picks the one that stands out against the background, and it goes back to null whenever the background changes.
Can be nullOne of"dark""light"

`DeletedOutOfOffice`object

objectstringRequired: One of"out_of_office"
addressstringRequired
deletedbooleanRequired: One oftrue

`DeletedSignature`object

objectstringRequired: One of"signature"
idstringRequired
addressstringRequired: The address the signature belonged to.
deletedbooleanRequired: One oftrue

`OutOfOffice`object

objectstringRequired: One of"out_of_office"
addressstringRequired: The address the reply is for, or *@example.com for a catch-all.
enabledbooleanRequired: Whether the reply is switched on.
activebooleanRequired: Whether mail arriving now is answered: it is on, startsAt has passed and endsAt has not.
startsAtstringRequired: When the reply starts. Null when none was ever saved.
Can be nullFormatdate-time
endsAtstringRequired: When it stops. Null keeps it on until it is switched off.
Can be nullFormatdate-time
subjectstringRequired: The subject of the reply. Empty answers with Re: and the subject received.
Up to 255 characters
messagestringRequired: The reply, as plain text. Line breaks are kept.
Up to 10000 characters
contactsOnlybooleanRequired: Answer only contacts and people the workspace has written to.
updatedAtstringRequired: The last save. Null when none was ever saved.
Can be nullFormatdate-time

`OutOfOfficeList`object

objectstring: One of"list"
dataOutOfOffice[]

`Settings`object

objectstringRequired

One of"settings"

addressstringRequired

The scope the call named, lowercased: an address, *@domain for a catch-all or @domain for a whole domain. Null when the call named none.

Can be null

timezonestringRequired

timeFormatstringRequired

One of"12h""24h"Default"24h"

dateFormatstringRequired

One of"dmy""mdy""ymd"Default"dmy"

weekStartstringRequired

One of"monday""sunday"Default"monday"

workspaceNamestring

externalImagesbooleanRequired

Defaulttrue

semanticSearchbooleanRequired

Defaulttrue

replySuggestionsbooleanRequired

Defaulttrue

knowledgeLearningbooleanRequired

Defaulttrue

trustedSendersstring[]

colorThemestringRequired

One of"light""dark""system"Default"system"

openEmailSignaturebooleanRequired

Defaulttrue

signaturestringRequired

Up to 150000 characters

defaultEmailAliasstring

undoSendEnabledbooleanRequired

Defaultfalse

trackOpensbooleanRequired

Defaultfalse

trackClicksbooleanRequired

Defaultfalse

imageCompressionstringRequired

One of"low""medium""original"Default"medium"

attachmentDeliverystringRequired

One of"mime""link""auto"Default"auto"

autoReadbooleanRequired

Defaulttrue

aiWrittenLabelbooleanRequired

Defaulttrue

animationsbooleanRequired

Defaulttrue

desktopNewMailbooleanRequired

Defaulttrue

desktopOnlyWhenHiddenbooleanRequired

Defaultfalse

phoneNewMailbooleanRequired

Defaulttrue

phoneRepliesbooleanRequired

Defaulttrue

phoneScheduledSendbooleanRequired

Defaultfalse

phoneFollowUpsbooleanRequired

Defaulttrue

inboxTabsbooleanRequired

Defaultfalse

primaryOnlyAlertsbooleanRequired

Defaulttrue

phoneSendFailuresbooleanRequired

Defaulttrue

phonePreviewsbooleanRequired

Defaulttrue

phoneSoundbooleanRequired

Defaulttrue

phoneMutedWorkspacesstring[]Required

Up to 200 itemsDefault[]

soundNewMailbooleanRequired

Defaulttrue

soundAiDonebooleanRequired

Defaulttrue

soundSentbooleanRequired

Defaulttrue

blockedSendersstring[]Required

Default[]

blockedDomainsstring[]Required

Default[]

blockedWordsstring[]Required

Default[]

useDefaultBlockedWordsbooleanRequired

Defaultfalse

translateLanguagestringRequired

Default""

translateRepliesbooleanRequired

Defaulttrue

showAvatarToContactsbooleanRequired

Defaulttrue

lookupContactPhotosbooleanRequired

Defaulttrue

marketingSenderNamestringRequired

Up to 120 charactersDefault""Pattern^[^\u0000-\u001F\u007F]*$

marketingPostalAddressstringRequired

Up to 500 charactersDefault""Pattern^[^\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]*$

overridesobjectRequired

What the scope sets itself, the fields a PATCH to the same scope can send null for. Without address it is the workspace's own privacy fields, with an address or a catch-all its own signature, footer, tracking, externalImages, trustedSenders and blocklist, and with @domain its own externalImages, trustedSenders and blocklist. A field that is not here is inherited.

signaturestring: Up to 150000 characters
openEmailSignatureboolean
trackOpensboolean
trackClicksboolean
externalImagesboolean
trustedSendersstring[]
blockedSendersstring[]
blockedDomainsstring[]
blockedWordsstring[]
useDefaultBlockedWordsboolean
semanticSearchboolean
replySuggestionsboolean
knowledgeLearningboolean
marketingSenderNamestring: Up to 120 charactersPattern^[^\u0000-\u001F\u007F]*$
marketingPostalAddressstring: Up to 500 charactersPattern^[^\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]*$

`Signature`object

objectstringRequired: One of"signature"
idstringRequired: The id, which starts with sig_.
addressstringRequired: The address the signature belongs to, or *@example.com for a catch-all.
namestringRequired: What the signature is called in the app. Unique on its address, whatever the case.
Up to 80 characters
htmlstringRequired: The signature as sanitised HTML, the way it is added under a message.
Up to 150000 characters
isDefaultbooleanRequired: Whether new mail from the address carries this signature unless the send says otherwise.
isReplyDefaultbooleanRequired: Whether replies and forwards from the address carry this signature unless the send says otherwise.
createdAtstringRequired: When the signature was created.
Formatdate-time
updatedAtstringRequired: When its name or HTML last changed.
Formatdate-time

`SignatureCopyList`object

objectstring: One of"list"
dataSignature[]

`SignatureList`object

objectstring: One of"list"
dataSignature[]
hasMoreboolean: True when another page follows. Pass nextCursor back as cursor to read it.
nextCursorstring: An opaque cursor for the next page, or null on the last page. Pass it back unchanged.
Can be null

Settings

Operations

Returns

Errors

Also available in

Request body

Returns

Errors

Also available in

Path parameters

Request body

Returns

Errors

Also available in

Path parameters

Returns

Errors

Also available in

Query parameters

Returns

Errors

Also available in

Query parameters

Request body

Returns

Errors

Also available in

Query parameters

Returns

Errors

Also available in

Query parameters

Request body

Returns

Errors

Also available in

Query parameters

Returns

Errors

Also available in

Query parameters

Returns

Errors

Also available in

Request body

Returns

Errors

Also available in

Path parameters

Returns

Errors

Also available in

Path parameters

Request body

Returns

Errors

Also available in

Path parameters

Returns

Errors

Also available in

Path parameters

Request body

Returns

Errors

Also available in

Objects

Brandingobject

DeletedOutOfOfficeobject

DeletedSignatureobject

OutOfOfficeobject

OutOfOfficeListobject

Settingsobject

Signatureobject

SignatureCopyListobject

SignatureListobject

Your inbox,on your own terms.

`Branding`object

`DeletedOutOfOffice`object

`DeletedSignature`object

`OutOfOffice`object

`OutOfOfficeList`object

`Settings`object

`Signature`object

`SignatureCopyList`object

`SignatureList`object

Your inbox,
on your own terms.