Sharing
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
Public links to templates, forms and automations, the Share button on each of them in the app. Everything is private until it is shared, and a shared item is a page anyone with the link can open without an account, where they can try it: fill in a template's props, type into a form, follow an automation step by step. With copyable on, anyone signed in can also copy it into their own workspace.
A copy carries the design only: never the submissions, sends, runs or contacts the original collected, and never the audiences, addresses, forms or webhook endpoints it points at, which stay with the owner and are left empty for you to fill in. The templates an automation sends are copied with it, and the images a template shows are copied into your workspace.
GET/share-links
List the public links
Every template, form and automation of this workspace that is public, newest link first, with how often each was opened and copied. kind keeps one of the three. A key sees the kinds its scopes read: templates:read for templates, forms:read for forms and automations:read for automations, and the others are left out. A member's token sees the templates and the forms and automations that member made.
Requires the templates:read scope, or forms:read or automations:read in its place.
Query parameters
kindstringOnly links to this kind of item. Left out, all three.
One of"template""form""automation"limitintegerRows per page, 1 to 100.
At least 1At most 100Default50cursorstringThe id of the last link on the previous page. Keyset, not offset: pass the previous page's
nextCursor. One that names nothing in this list is a 400invalid_cursor.
Returns
A page of public links, newest first.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
shareLinks.list()shareLinks.listAll()shareLinks.iterate()- Python
share_links.list()share_links.list_all()share_links.iterate()- Ruby
share_links.listshare_links.list_allshare_links.iterate- PHP
shareLinks->listshareLinks->listAllshareLinks->iterate- Go
ShareLinks.ListShareLinks.ListAllShareLinks.Iterate- Java
shareLinks().listshareLinks().listAllshareLinks().iterate- C#
ShareLinks.ListAsyncShareLinks.ListAllAsyncShareLinks.IterateAsync- CLI
nextmail share-links list- MCP
listShareLinks
GET/share-links/{kind}/{itemId}
Read the public link of an item
The public link of one template, form or automation, with how often it was opened and copied. Reading it takes the read scope of its kind. A private item answers 404 share_link_not_found, and an item this workspace does not hold, or a member cannot reach, answers 404 resource_not_found.
Requires the templates:read scope, or forms:read or automations:read in its place.
Path parameters
kindstringRequiredWhat the item is:
template,formorautomation.One of"template""form""automation"itemIdstringRequiredThe template, form or automation, by the id
GET /templates,GET /formsorGET /automationsreturns.
Returns
The public link.
Errors
- 404
share_link_not_found: the item is private.resource_not_found: no such item here.
The errors every operation can return400401403422429500Error catalog
Also available in
- TypeScript
shareLinks.get()- Python
share_links.get()- Ruby
share_links.get- PHP
shareLinks->get- Go
ShareLinks.Get- Java
shareLinks().get- C#
ShareLinks.GetAsync- CLI
nextmail share-links get- MCP
getShareLink
PUT/share-links/{kind}/{itemId}
Make an item public
Shares one template, form or automation at a public link, as Share does in the app, and answers the link. Sharing takes the write scope of its kind. An item that is already public keeps its link, so the call is safe to repeat: copyable changes whether people may copy it, and leaving it out keeps what it was, which is true for a new link.
The page shows what is live: a template's published version, a form's published design and an automation's published flow, or the draft when nothing was published yet. A copy carries the design only: never the submissions, sends, runs or contacts the original collected, and never the audiences, addresses, forms or webhook endpoints it points at, which stay with the owner and are left empty for you to fill in. The templates an automation sends are copied with it, and the images a template shows are copied into your workspace.
Requires the templates:write scope, or forms:write or automations:write in its place.
Path parameters
kindstringRequiredWhat the item is:
template,formorautomation.One of"template""form""automation"itemIdstringRequiredThe template, form or automation, by the id
GET /templates,GET /formsorGET /automationsreturns.
Request body
copyablebooleantruelets anyone signed in copy the item into their own workspace from the page, andfalselets people only look at it. Left out, a new link is copyable and a link that already exists keeps what it had.
Returns
The public link, new or as it was.
Errors
- 404
resource_not_found: no such item here.
The errors every operation can return400401403422429500Error catalog
Also available in
- TypeScript
shareLinks.set()- Python
share_links.set()- Ruby
share_links.set- PHP
shareLinks->set- Go
ShareLinks.Set- Java
shareLinks().set- C#
ShareLinks.SetAsync- CLI
nextmail share-links set- MCP
setShareLink
DELETE/share-links/{kind}/{itemId}
Make an item private
Takes the public link down, as turning Share off does in the app: the page stops working at once for everyone who has the link, and copies already made stay where they are. Making it public again gives it a new link. A private item answers 404 share_link_not_found.
Requires the templates:write scope, or forms:write or automations:write in its place.
Path parameters
kindstringRequiredWhat the item is:
template,formorautomation.One of"template""form""automation"itemIdstringRequiredThe template, form or automation, by the id
GET /templates,GET /formsorGET /automationsreturns.
Returns
The link that stopped working.
Errors
- 404
share_link_not_found: the item is already private.resource_not_found: no such item here.
The errors every operation can return400401403422429500Error catalog
Also available in
GET/shared/{token}
Read a shared item
What the public page of a link shows, from any workspace: the item's name and description, the workspace that shares it, whether it may be copied, and its content. A template comes rendered with the sample values of its props, a form with its design, and an automation with its flow and the templates it sends. The audiences, addresses, forms and webhook endpoints an automation points at are left empty, and a form's audience choices keep their labels only. Reading it takes the read scope of the item's kind, and it does not count as a view of the page.
Requires the templates:read scope, or forms:read or automations:read in its place.
Path parameters
tokenstringRequiredThe token at the end of a public link,
tokenon a share link, or the last part of itsurl.
Returns
The shared item.
Errors
- 404
shared_item_not_found: no shared item has that link, because the owner made it private or deleted it.
The errors every operation can return400401403422429500Error catalog
Also available in
- TypeScript
shared.get()- Python
shared.get()- Ruby
shared.get- PHP
shared->get- Go
Shared.Get- Java
shared().get- C#
Shared.GetAsync- CLI
nextmail shared get
POST/shared/{token}/copy
Copy a shared item into this workspace
Copies the item at a public link into this workspace as a new draft, as Copy to my workspace does on the page, and answers the copy's id. Copying takes the write scope of the item's kind, and an automation that sends templates also takes templates:write. A template whose name is taken here gets a number after it. Workspace limits apply as they do to anything created here.
A copy carries the design only: never the submissions, sends, runs or contacts the original collected, and never the audiences, addresses, forms or webhook endpoints it points at, which stay with the owner and are left empty for you to fill in. The templates an automation sends are copied with it, and the images a template shows are copied into your workspace.
Requires the templates:write scope, or forms:write or automations:write in its place.
Path parameters
tokenstringRequiredThe token at the end of a public link,
tokenon a share link, or the last part of itsurl.
Returns
The copy, a draft in this workspace.
Errors
- 403
share_not_copyable: the owner shares it to look at, not to copy.- 404
shared_item_not_found: no shared item has that link.
The errors every operation can return400401422429500Error catalog
Also available in
- TypeScript
shared.copy()- Python
shared.copy()- Ruby
shared.copy- PHP
shared->copy- Go
Shared.Copy- Java
shared().copy- C#
Shared.CopyAsync- CLI
nextmail shared copy- MCP
copySharedItem
Objects
AutomationDefinitionobject
What starts an automation and what it then does. Paths never join or loop: every step is reached from exactly one place, and a definition holds at most 50 steps.
triggerobjectRequiredWhat puts a contact into the automation. Null in a draft that has none yet, and a draft cannot be published without one.
Can be nullkindstringRequired- One of
"audience_joined" audienceIdstringRequired- Up to 64 characters
includeImportedbooleanRequired
entrystringRequiredThe
keyof the first step, or null while the draft has no steps.Can be nullPattern^[a-z][a-z0-9]{2,23}$stepsobject[]RequiredEvery step, in any order. Each has a unique
key, and names the step after it by key innext, or inyesandnofor a branch. Null ends the path there.Up to 50 itemskeystringRequired- Pattern
^[a-z][a-z0-9]{2,23}$ namestring- Up to 80 characters
kindstringRequired- One of
"send_email" nextstringRequired- Can be nullPattern
^[a-z][a-z0-9]{2,23}$ templateIdstringRequired- Up to 64 characters
templateVersionintegerRequired- Can be nullAt least 1
fromobjectRequiredemailstringRequired- Up to 320 characters
namestring- Up to 120 characters
replyTostringRequired- Can be nullUp to 320 characters
subjectstringRequired- Can be nullUp to 300 characters
propsRecord<string, object>Required
AutomationSettingsobject
timezonestringRequiredThe IANA time zone the sending window and waits until a day and time are read in, such as
Europe/London.UTCuntil you set one.1 to 64 characterssendWindowobjectRequiredWhen emails may go out:
daysof the week (0 is Sunday) andstartMinutetoendMinuteof the day, counted from midnight. An email due outside it waits for the window to open. Null sends at any time.Can be nulldaysinteger[]Required- Up to 7 items
startMinuteintegerRequired- At least 0At most 1440
endMinuteintegerRequired- At least 0At most 1440
reentryDaysintegerRequiredHow many days after a contact finishes before they may enter again. Null lets each contact through once only.
Can be nullAt least 0At most 3650exitOnLeavebooleanRequiredTake a contact out when they leave the audience that started the automation. True by default.
listAudienceIdstringRequiredThe audience an unsubscribe from one of these emails is recorded in. A contact who unsubscribed from it is not sent to and cannot be enrolled. Null uses the audience that starts the automation, or the built-in audience of every contact when no audience starts it.
Can be nullUp to 64 characters
DeletedShareLinkobject
objectstringRequired- One of
"share_link" idstringRequiredkindstringRequired- One of
"template""form""automation" itemIdstringRequiredThe template, form or automation the link shows.
itemNamestringRequiredIts name, as it is now.
tokenstringRequiredThe secret part of the link.
GET /shared/{token}andPOST /shared/{token}/copytake it.urlstringRequiredThe public page anyone with the link can open, without an account.
FormaturicopyablebooleanRequiredTrue when people may copy the item into their own workspace from the page, false when they may only look at it.
viewsintegerRequiredHow often the public page was opened.
At least 0copiesintegerRequiredHow often the item was copied into a workspace from the link.
At least 0lastViewedAtstringRequired- Can be nullFormat
date-time lastCopiedAtstringRequired- Can be nullFormat
date-time createdAtstringRequiredWhen the item was made public at this link.
Formatdate-timeupdatedAtstringRequired- Format
date-time deletedbooleanRequired- One of
true
FormDocumentobject
Everything a visitor sees: fields in order, the copy around them and the style. Every form has exactly one email field, and every input field has a unique key that answers are posted under.
fieldsobject[]Required- 1 to 50 items
idstringRequired- 1 to 64 characters
typestringRequired- One of
"email""text""textarea""number""phone""url""date""select""radio""checkboxes""checkbox""consent""audiences""hidden""heading""paragraph""divider" keystringRequired- Up to 40 charactersPattern
^[a-z][a-z0-9_]{0,39}$ labelstringRequired- Up to 300 characters
placeholderstringRequired- Can be nullUp to 200 characters
helpstringRequired- Can be nullUp to 1000 characters
requiredbooleanRequireddefaultValuestringRequired- Can be nullUp to 1000 characters
optionsobject[]Required- Up to 50 items
idstringRequired- 1 to 64 characters
labelstringRequired- 1 to 300 characters
valuestringRequired- 1 to 1000 characters
mapsTostringRequiredThe contact detail this field fills when the sign-up is accepted, or null for none.
emailgoes on the email field.firstName,lastName,name,companyandjobTitlego on atextfield,phoneon aphonefield,websiteon aurlfield andbirthdayon adatefield. One field per detail, andnamenever together withfirstNameorlastName. The name is saved on the contact. The phone number, company, job title, website and birthday are saved on the contact card, and only where the card has nothing yet: a company, job title or birthday already there is kept, and a phone number or website the card already lists is not added again.Can be nullOne of"email""firstName""lastName""name""phone""company""jobTitle""website""birthday"saveAsstringA custom field of the contact this field fills when the sign-up is accepted, such as
plan, or null for none. A key starts with a letter and holds up to 64 letters, digits and underscores. The answer replaces the field of that name on the contact, an empty answer leaves it alone, and a choice of several options is saved as their labels joined by commas. Not on the email field or an audience choice, one field per custom field, and never together withmapsTo. Left out when a form is updated, a field keeps the custom field it had.Can be nullPattern^[A-Za-z][A-Za-z0-9_]{0,63}$widthstringRequired- One of
"full""half" minLengthintegerRequired- Can be nullAt least 0At most 5000
maxLengthintegerRequired- Can be nullAt least 1At most 5000
minnumberRequired- Can be nullAt least -1000000000000At most 1000000000000
maxnumberRequired- Can be nullAt least -1000000000000At most 1000000000000
copyobjectRequiredtitlestringRequired- Up to 200 characters
descriptionstringRequired- Can be nullUp to 2000 characters
submitLabelstringRequired- 1 to 60 characters
successTitlestringRequired- Up to 200 characters
successMessagestringRequired- Up to 2000 characters
pendingTitlestringRequired- Up to 200 characters
pendingMessagestringRequired- Up to 2000 characters
closedTitlestringRequired- Up to 200 characters
closedMessagestringRequired- Up to 2000 characters
footerstringRequired- Can be nullUp to 2000 characters
styleobjectRequiredaccentstringRequired- Pattern
^#[0-9a-fA-F]{6}$ backgroundstringRequired- Pattern
^#[0-9a-fA-F]{6}$ surfacestringRequired- Pattern
^#[0-9a-fA-F]{6}$ textstringRequired- Pattern
^#[0-9a-fA-F]{6}$ fontstringRequired- One of
"system""sans""serif""mono" radiusstringRequired- One of
"none""sm""md""lg""full" widthstringRequired- One of
"narrow""normal""wide" layoutstringRequired- One of
"card""plain" alignstringRequired- One of
"left""center" logoUrlstringRequired- Can be nullUp to 2000 charactersFormat
uri
ShareLinkobject
objectstringRequired- One of
"share_link" idstringRequiredkindstringRequired- One of
"template""form""automation" itemIdstringRequiredThe template, form or automation the link shows.
itemNamestringRequiredIts name, as it is now.
tokenstringRequiredThe secret part of the link.
GET /shared/{token}andPOST /shared/{token}/copytake it.urlstringRequiredThe public page anyone with the link can open, without an account.
FormaturicopyablebooleanRequiredTrue when people may copy the item into their own workspace from the page, false when they may only look at it.
viewsintegerRequiredHow often the public page was opened.
At least 0copiesintegerRequiredHow often the item was copied into a workspace from the link.
At least 0lastViewedAtstringRequired- Can be nullFormat
date-time lastCopiedAtstringRequired- Can be nullFormat
date-time createdAtstringRequiredWhen the item was made public at this link.
Formatdate-timeupdatedAtstringRequired- Format
date-time
ShareLinkListobject
objectstring- One of
"list" dataShareLink[]hasMorebooleanTrue when another page follows. Pass
nextCursorback ascursorto read it.nextCursorstringThe id of the last row on this page, or null on the last page.
Can be null
SharedAutomationobject
definitionAutomationDefinitionRequiredtemplatesSharedAutomationTemplate[]RequiredThe template each send step sends, by the step it belongs to.
settingsAutomationSettingsRequired
SharedAutomationTemplateobject
stepKeystringRequiredThe send step that sends it.
namestringRequiredsubjectstringRequired
SharedCopyobject
objectstringRequired- One of
"shared_copy" kindstringRequired- One of
"template""form""automation" idstringRequiredThe new template, form or automation, a draft here.
namestringRequiredtemplateIdsstring[]RequiredThe templates copied along with an automation, empty for the rest.
SharedFormobject
documentFormDocumentRequireddoubleOptInbooleanRequiredTrue when the form asks people to confirm their address before they join.
SharedItemobject
objectstringRequired- One of
"shared_item" kindstringRequired- One of
"template""form""automation" tokenstringRequirednamestringRequireddescriptionstringRequired- Can be null
workspaceNamestringRequiredThe workspace that shares it, empty when it has no name.
copyablebooleanRequiredsharedAtstringRequired- Format
date-time templateSharedTemplateRequiredformSharedFormRequiredautomationSharedAutomationRequired
SharedTemplateobject
subjectstringRequiredThe subject, with the sample values filled in.
enginestringRequired- One of
"blocks""html" slotsTemplateSlot[]RequiredpropsTemplateProp[]RequiredhtmlstringRequiredThe email rendered with the sample values.
textstringRequiredThe plain text part, rendered the same way.
unfilledstring[]RequiredThe props and slots that have no sample value, so they render empty.
TemplatePropobject
keystringA letter followed by letters, digits or underscores. This is what
{{key}}in the subject or the body refers to, and what a send names inpropsorslots.labelstringFor whoever fills it in. Never rendered into the message.
kindstringHow a supplied value is escaped when it lands in the body.
textbecomes a React child, so React escapes it;urlandimageare parsed and scheme-checked before they reach anhrefor asrc. The kind is declared rather than sniffed from the value, because a string that happens to start withhttps:is not evidence that the author meant it to be followed.One of"text""url""image"requiredbooleanA required prop missing at send is a 422 and no mail leaves. That refusal is the most valuable rule in the feature: the alternative is a message going out with a blank where the order number should be, which nothing reports, nobody notices, and no one can recall.
defaultstringUsed when the caller names nothing. Null means there is no fallback: either the prop is required and its absence is refused, or it renders empty.
Can be null
TemplateSlotobject
keystringA letter followed by letters, digits or underscores. This is what
{{key}}in the subject or the body refers to, and what a send names inpropsorslots.labelstringFor whoever fills it in. Never rendered into the message.
kindstringHow a supplied value is escaped when it lands in the body.
textbecomes a React child, so React escapes it;urlandimageare parsed and scheme-checked before they reach anhrefor asrc. The kind is declared rather than sniffed from the value, because a string that happens to start withhttps:is not evidence that the author meant it to be followed.One of"text""url""image"defaultstringWhat renders when nobody overrides it. Never null. A slot always has something to fall back to, which is the difference between it and a prop.
Google Workspace