Mail. 39 operations.
39 of them work. Page 1 of 2. Each needs a bearer token with its scope. All operations.
Operations
GET/api/v1/mail/blocksmail.blocksmail.read
GET/api/v1/mail/calendarmail.calendarmail.read
POST/api/v1/mail/mailings/{id}/cancelmail.cancel-mailingmail.write
GET/api/v1/mail/contactsmail.contactsmail.read
Parameters
emailquery | stringOnly the contacts whose address contains this text, in any case. |
topicquery | stringA topic key: status is then the contact's status for that topic. |
statusquery | stringOnly the contacts of this status: consented, withdrawn, pending or none; suppressed for the addresses on the suppression list. |
afterquery | stringThe cursor of the page: the next of the page before; the first address when left out. |
limitquery | integerThe most contacts in the page: 1 to 500; 100 when left out. |
Answer
Errors: 401, 403, 405, 422, 429
curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/contacts
POST/api/v1/mail/mailings/{id}/copymail.copy-mailingmail.write
GET/api/v1/mail/dmarcmail.dmarcmail.read
GET/api/v1/mail/flows/{kind}/reportmail.flow-reportmail.read
GET/api/v1/mail/flows/{kind}/runsmail.flow-runsmail.read
POST/api/v1/mail/flows/{kind}mail.flow-savemail.write
GET/api/v1/mail/flowsmail.flowsmail.read
POST/api/v1/mail/importsmail.importmail.write
POST/api/v1/mail/imports/previewmail.import-previewmail.read
GET/api/v1/mail/importsmail.importsmail.read
POST/api/v1/mail/kindsmail.kind-setmail.write
GET/api/v1/mail/kindsmail.kindsmail.read
POST/api/v1/mail/suppressions/{hash}/liftmail.lift-suppressionmail.write
GET/api/v1/mail/mailings/{id}mail.mailingmail.read
GET/api/v1/mail/mailings/{id}/reportmail.mailing-reportmail.read
GET/api/v1/mail/mailingsmail.mailingsmail.read
Read a page at a time: give limit (1 to 500; 100 when none is given) and after, the Next-Cursor of the page before. Follow the Link, rel next, to the rest.
Parameters
limitquery | integerThe most mailings in the page: 1 to 500; 100 when the call gives no limit. The Next-Cursor and Link headers name the next page. |
afterquery | stringSee common parameters |
Answer
array of MailingSummary
Errors: 400, 401, 403, 405, 422, 429
curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/mailings
GET/api/v1/mail/next-allowedmail.next-allowedmail.read
Schemas 42
DMARCSource
DMARCSource is what the DMARC aggregate reports of the last 30 days say of one source IP and result: how many mails it sent, and their SPF, DKIM and DMARC results, pass or fail.
countrequired | integer |
dkimrequired | string |
dmarcrequired | string |
iprequired | string |
spfrequired | string |
MailBlockField
MailBlockField is a field of a block. Type says what control it needs: line (one line of words), markdown (the engine's Markdown subset), number, image (the name of an image the store holds), url (https, or a path of the store), slug (one product), slugs (products) or code (a coupon code). Min and Max are the limit of the words in characters, of a list in items, or of a number; absent for none. Merge says a merge field may stand in it.
max | integer |
merge | boolean |
min | integer |
namerequired | string |
requiredrequired | boolean |
typerequired | string |
MailBlockKind
MailBlockKind is a kind of block: the fields it takes and the contexts it may be written in: "campaign" and "flow". The blocks cart, order and recommendations are for flows alone.
contextsrequired | array of string |
fieldsrequired | array of MailBlockField |
kindrequired | string |
MailBlocks
MailBlocks is everything one editor needs to build the forms of a campaign's and a flow step's document: the kinds of block, the merge fields a words field may hold, and the limits of a document.
kindsrequired | array of MailBlockKind |
limitsrequired | MailLimits |
merge_fieldsrequired | array of string |
MailCalendar
MailCalendar is one month of the mail calendar, by day in the store's zone: the mailings that are scheduled, sending, paused or sent that day, and the steps of flows that are due that day, as counts. A day with nothing is left out. A mailing stands on the day it started, or, until it starts, the day it is to start. Flow steps are counted for the runs that are active and due that day; the quiet hours and the frequency caps are not applied to the count: it says due, not will go.
daysrequired | array of MailCalendarDay |
monthrequired | string |
zonerequired | string |
MailCalendarDay
MailCalendarDay is one day of the calendar, as 2026-10-19.
daterequired | string |
flowsrequired | array of MailCalendarFlow |
mailingsrequired | array of MailCalendarMailing |
MailCalendarFlow
MailCalendarFlow is how many steps of a flow are due on a day.
duerequired | integer |
flowrequired | string |
MailCalendarMailing
MailCalendarMailing is a mailing on a day: At is when it started, or is to start. Recipients is how many mails it froze at its start: 0 until it starts (the audience of a mailing not yet started is counted by mail.mailings).
atrequired | string (date-time) |
idrequired | integer |
namerequired | string |
recipientsrequired | integer |
statusrequired | string |
topicrequired | string |
MailContact
MailContact is a contact: an address the store knows, what first named it and when, when an import last named it, whether it stands suppressed, and its topics.
added_atrequired | string (date-time) |
emailrequired | string |
imported_at | string (date-time) |
sourcerequired | string |
suppressedrequired | boolean |
suppressed_reason | string |
topicsrequired | array of MailContactTopic |
MailContactTopic
MailContactTopic is a contact's status for a topic it has a consent record of: consented, withdrawn or pending (asked, not yet confirmed), and since when.
atrequired | string (date-time) |
statusrequired | string |
topicrequired | string |
MailContactTotals
MailContactTotals count the whole store's contacts, whatever the list filters: all; those who can get marketing mail (some consent stands and the address is not suppressed); those who withdrew, with none standing; those whose address stands suppressed.
can_get_marketingrequired | integer |
contactsrequired | integer |
suppressedrequired | integer |
withdrawnrequired | integer |
MailContactsPage
MailContactsPage is a page of the contacts, the totals of the store (the first page only), and where the next page starts.
contactsrequired | array of MailContact |
morerequired | boolean |
nextrequired | string |
totals | MailContactTotals |
MailFlow
MailFlow is a flow as the store runs it. Kind names it: a store runs at most one flow of each. Enabled is whether it is on; a flow whose kind has an audience setting is off, whatever the owner says, until store.yaml sets Audience, and one with no steps saved cannot run. Version is the version of the steps in use. Runs counts its runs by state: active, completed, exited and held_out.
audience | string |
default | boolean |
due_next_24hrequired | integer |
enabledrequired | boolean |
held_off | string |
holdout_percentrequired | integer |
kindrequired | string |
reentry_daysrequired | integer |
runsrequired | map of integer |
stepsrequired | array of MailFlowStep |
topicrequired | string |
versionrequired | integer |
MailFlowGroup
MailFlowGroup is the verdicts of one group of runs: the runs whose window ended, how many of their contacts placed a paid order within attribution_days of the start, the rate of those in permille of the runs counted, and the revenue of their orders.
convertedrequired | integer |
countedrequired | integer |
rate_permillerequired | integer |
revenuerequired | Money |
MailFlowHoldout
MailFlowHoldout compares the contacts whose run was held out with the rest: the two groups, how many runs wait for the end of their window (Open), and the difference of the rates in permille, the rest less the hold-out (0 until both groups have a run counted). Note says in words why no verdict is given, in link mode.
difference_permillerequired | integer |
held_outrequired | MailFlowGroup |
note | string |
openrequired | integer |
restrequired | MailFlowGroup |
rest_noterequired | string |
undecidablerequired | integer |
undecidable_why | string |
MailFlowReport
MailFlowReport is what a flow brought, as of ComputedAt. Runs counts the runs by state and HeldOut is the size of the hold-out. OrdersNote says in words that the order rates of the hold-out and of the rest need clicks counted by person; empty when they are.
computed_atrequired | string (date-time) |
flowrequired | string |
held_outrequired | integer |
holdout | MailFlowHoldout |
orders_note | string |
runsrequired | map of integer |
stepsrequired | array of MailFlowStepReport |
MailFlowRun
MailFlowRun is one contact's run of a flow. Address is empty once the run ended more than the report window ago: only the hash of it is kept then.
address | string |
ended | string (date-time) |
exit | string |
held_out | boolean |
idrequired | integer |
next | string (date-time) |
startedrequired | string (date-time) |
staterequired | string |
steprequired | integer |
triggerrequired | string |
versionrequired | integer |
withheld | integer |
MailFlowSave
MailFlowSave is the owner's edit of a flow: whether it is on, the share of its runs held out when given (0 to 50), and the document of each step, in the order of the steps store.yaml sets. A change of the documents makes a new version, which only the runs that start later use. Turning a flow off ends its active runs. A document may be null for a mail not written yet: the flow is kept so, and cannot be switched on until every step has one (the refusal names the mails still to write).
documentsrequired | array of any |
enabledrequired | boolean |
holdout_percent | integer |
MailFlowStep
MailFlowStep is one mail of a flow: its delay from the start of the run, as a duration such as "30m" or "48h" that store.yaml sets, and its document, as a mailing's (a subject and blocks, with the merge fields of ), which the owner edits. A flow always lists the steps store.yaml sets; Document is absent for a step with no mail saved and no default.
afterrequired | string |
document | any |
MailFlowStepReport
MailFlowStepReport is what became of the mails of one step of a flow: queued, sent, withheld (by the frequency cap, or with the consent) and failed. Step counts from 0.
bouncedrequired | integer |
clicksrequired | integer |
complaintsrequired | integer |
deliveredrequired | integer |
failedrequired | integer |
mails_clickedrequired | integer |
ordersrequired | integer |
queuedrequired | integer |
revenuerequired | Money |
sentrequired | integer |
steprequired | integer |
unsubscribesrequired | integer |
withheldrequired | integer |
MailImport
MailImport is an import in the history: who made it, when, from which service and file, its rows by outcome, and the topics it was given as a fallback. Refused is how many rows were bad in a file the import refused; 0 for a file it wrote.
atrequired | string (date-time) |
byrequired | string |
file_namerequired | string |
idrequired | integer |
keptrequired | integer |
refusedrequired | integer |
rowsrequired | integer |
servicerequired | string |
skippedrequired | integer |
subscribedrequired | integer |
suppressedrequired | integer |
topicsrequired | array of string |
unchangedrequired | integer |
MailImportCounts
MailImportCounts are the rows of a file by outcome.
badrequired | integer |
keptrequired | integer |
skippedrequired | integer |
subscriberequired | integer |
suppressrequired | integer |
unchangedrequired | integer |
MailImportMapping
MailImportMapping says how a file's columns and words read. Columns maps each of email, name, topics, status and date to the file's header it is read from; a name left out is read from the header of that name. Statuses maps the file's words to subscribed, unsubscribed, bounced, cleaned or skip; a word left out is read as itself. Topics are given to a subscribed row that names none.
columns | map of string |
statuses | map of string |
topics | array of string |
MailImportPreview
MailImportPreview is what an import would do, and nothing is written. Unmapped are the required columns (email, status) no header supplies; the counts are then all zero.
bad_rowsrequired | array of MailImportRow |
countsrequired | MailImportCounts |
headerrequired | array of string |
pagerequired | array of MailImportRow |
rowsrequired | integer |
samplerequired | array of string |
status_valuesrequired | array of MailImportStatusValue |
unmappedrequired | array of string |
MailImportRequest
MailImportRequest is a file to import, or to preview: the CSV text, at most 5 MiB and 100,000 data rows, the service it comes from (lower-case letters, digits and hyphens), its name for the record, and the mapping, which may be empty. Offset and Limit choose the page of rows a preview gives; the write ignores them.
filerequired | string |
file_name | string |
limit | integer |
mappingrequired | MailImportMapping |
offset | integer |
servicerequired | string |
MailImportRow
MailImportRow is what a row does: its line in the file, its address, the topics it subscribes to, the tags it gives (MX2), its outcome (subscribe, suppress, kept, unchanged, skipped or bad) and, for a bad or kept row, why.
emailrequired | string |
linerequired | integer |
outcomerequired | string |
reason | string |
tagsrequired | array of string |
topicsrequired | array of string |
MailImportStatusValue
MailImportStatusValue is a word of the status column and how many rows have it.
rowsrequired | integer |
wordrequired | string |
MailKind
MailKind is a kind of transactional mail: what it is for and when it goes, in the storefront contract's words; whether it is on; whether the owner can switch it (AlwaysOn kinds are the mail a buyer needs to sign in, to change an address, to confirm a consent or an alert, and to download); and who changed it last.
always_onrequired | boolean |
always_on_why | string |
changed_at | string (date-time) |
changed_by | string |
enabledrequired | boolean |
kindrequired | string |
purposerequired | string |
sentrequired | string |
streamrequired | string |
MailKindSet
MailKindSet switches a kind of mail on or off. A kind that is none, or an always-on kind switched off, is refused in words. A mail of a kind switched off is recorded in the mail log as not sent, with the reason app.mail_kind_off, and never queued to be sent. The status mail of an order that has downloads is sent whatever its kind is, as it carries the links.
enabledrequired | boolean |
kindrequired | string |
MailLimits
MailLimits are the limits of a document: its blocks, the characters of its subject, preview line, headings, texts and labels, and the products of a grid.
blocksrequired | integer |
grid_leastrequired | integer |
grid_mostrequired | integer |
headingrequired | integer |
labelrequired | integer |
preheaderrequired | integer |
subjectrequired | integer |
textrequired | integer |
MailNextAllowed
MailNextAllowed says when a mail of a stream, due at At, may go: transactional mail goes at once; marketing mail waits for the quiet hours to end. Held is true when it waits; Words says why.
allowed_atrequired | string (date-time) |
atrequired | string (date-time) |
heldrequired | boolean |
streamrequired | string |
words | string |
Mailing
Mailing is a mailing with its document: its summary, its document (JSON: a subject and blocks of heading, text, image, button, product, product_grid, coupon and divider), and when it was made.
audience | integer |
audience_frozen | boolean |
cancelled_at | string (date-time) |
createdrequired | string (date-time) |
documentrequired | any |
held_by | string |
held_until | string (date-time) |
held_why | string |
idrequired | integer |
left_out | MailingLeftOut |
namerequired | string |
preparing | boolean |
progressrequired | MailingProgress |
scheduled_by | string |
segment | string |
send_at | string (date-time) |
start_refusedrequired | array of string |
started | string (date-time) |
statusrequired | string |
subjectrequired | string |
topicrequired | string |
untracked_linksrequired | integer |
updatedrequired | string (date-time) |
view | string |
MailingLeftOut
MailingLeftOut are the contacts a mailing not yet started leaves out, by reason: Withdrew (their consent to its topic stands withdrawn), Suppressed (they consent, and their address is suppressed: bounced, complained, unsubscribed, imported, in a registry or by hand) and NoConsent (they never asked for the topic, or the request is not confirmed).
no_consentrequired | integer |
suppressedrequired | integer |
withdrewrequired | integer |
MailingLinkReport
MailingLinkReport is a link of a mailing and the clicks on it that were not automated.
clicksrequired | integer |
urlrequired | string |
MailingProgress
MailingProgress is how far a mailing's sending has come: the recipients frozen at its start, those held for their batch, those released and not yet tried, and those sent, failed and withheld.
failedrequired | integer |
finish_at | string (date-time) |
finish_late | boolean |
queuedrequired | integer |
recipientsrequired | integer |
sentrequired | integer |
waitingrequired | integer |
withdrawn | integer |
withheldrequired | integer |
MailingReport
MailingReport is what a mailing brought, as of ComputedAt. Mode is how the store counts clicks (link, person or off), which the numbers come from. Sent is the mail sent; Delivered the mail the provider reported delivered, or, for a stream whose provider reports none, the mail sent; Bounced and Complaints the suppressions that name a mail of the mailing; Unsubscribes the withdrawals made through the unsubscribe link of one. Clicks are those that are not automated; MailsClicked the mails they came from, counted in person mode alone. UntrackedLinks is how many links went out as written. Orders are those attributed to the mailing, in person mode alone; Revenue their charged totals less the refunds that were not declined, and RevenuePerMail the revenue of each delivered mail. OrdersNote says in words why the orders are not counted; empty when they are.
bouncedrequired | integer |
clicksrequired | integer |
complaintsrequired | integer |
computed_atrequired | string (date-time) |
deliveredrequired | integer |
linksrequired | array of MailingLinkReport |
mailingrequired | integer |
mails_clickedrequired | integer |
moderequired | string |
ordersrequired | integer |
orders_noterequired | string |
revenuerequired | Money |
revenue_per_mailrequired | Money |
sentrequired | integer |
test | MailingTestReport |
unsubscribesrequired | integer |
untracked_linksrequired | integer |
MailingSummary
MailingSummary is a mailing as the list shows it: its id, the owner's name for it, its topic, its saved segment ("" for every contact consenting to the topic), its status, its subject, and when it was last changed.
audience | integer |
audience_frozen | boolean |
cancelled_at | string (date-time) |
idrequired | integer |
left_out | MailingLeftOut |
namerequired | string |
preparing | boolean |
segment | string |
statusrequired | string |
subjectrequired | string |
topicrequired | string |
updatedrequired | string (date-time) |
MailingTestReport
MailingTestReport is the test of two subjects of a mailing. Skipped is true when the test share held fewer mails a variant than the minimum, which is an engine constant (50 in link mode, 20 in person mode): no test was run, every mail went with subject A, and SkippedWhy says so with the numbers. Metric is clicks or orders. Winner is "a" or "b" once picked, at PickedAt; Tie is true when the variants were equal and A took it. EndsAt is when the window ends.
arequired | MailingVariantReport |
brequired | MailingVariantReport |
ends_atrequired | string (date-time) |
metricrequired | string |
minimumrequired | integer |
per_variantrequired | integer |
picked_at | string (date-time) |
skippedrequired | boolean |
skipped_why | string |
tie | boolean |
too_few | boolean |
too_few_why | string |
winner | string |
MailingVariantReport
MailingVariantReport is what one subject of a test had: the mails sent with it, the clicks on them that were not automated (the mails they came from in person mode, the clicks in link mode) and the orders attributed to them (person mode alone).
clicksrequired | integer |
ordersrequired | integer |
sentrequired | integer |
Money
Money is an amount: in minor units of its ISO 4217 currency, and as the store displays it.
currencyrequired | string |
displayrequired | string |
minorrequired | integer |
Suppression
Suppression is an address on the mail's suppression list: the hash it is kept by, the address while the store may keep it (absent once erased), why (hard_bounce, complaint, unsubscribed, imported, registry or manual), the mail of the log that caused it, if one did, and when.
address | string |
atrequired | string (date-time) |
hashrequired | string |
lifted_at | string (date-time) |
mail | integer |
reasonrequired | string |
registry_at | string (date-time) |
SuppressionChange
SuppressionChange is what a lift did: whether it changed the suppression, and the suppression as it then stands.
changedrequired | boolean |
suppressionrequired | Suppression |
Made from engine/internal/openapi/openapi.json at commit 6c4cbd921. The contract-only operations come from the engine’s stub file, engine/internal/ops.