Tillwire Read the guide
API reference

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

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/blocks

GET/api/v1/mail/calendarmail.calendarmail.read

Parameters

monthquerystringThe month, as 2026-10, in the store's zone; the current month when left out.

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/calendar

POST/api/v1/mail/mailings/{id}/cancelmail.cancel-mailingmail.write

Parameters

idpathstring
idpathstring
Idempotency-KeyheaderstringSee common parameters

Answer

Mailing

Errors: 401, 403, 404, 405, 409, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/mailings/{id}/cancel

GET/api/v1/mail/contactsmail.contactsmail.read

Parameters

emailquerystringOnly the contacts whose address contains this text, in any case.
topicquerystringA topic key: status is then the contact's status for that topic.
statusquerystringOnly the contacts of this status: consented, withdrawn, pending or none; suppressed for the addresses on the suppression list.
afterquerystringThe cursor of the page: the next of the page before; the first address when left out.
limitqueryintegerThe most contacts in the page: 1 to 500; 100 when left out.

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

Parameters

idpathstring
idpathstring
Idempotency-KeyheaderstringSee common parameters

Answer

Mailing

Errors: 401, 403, 404, 405, 409, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/mailings/{id}/copy

GET/api/v1/mail/dmarcmail.dmarcmail.read

Answer

array of DMARCSource

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/dmarc

GET/api/v1/mail/flows/{kind}/reportmail.flow-reportmail.read

Parameters

kindpathstring
kindpathstring

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/flows/{kind}/report

GET/api/v1/mail/flows/{kind}/runsmail.flow-runsmail.read

Parameters

kindpathstring
kindpathstring

Answer

array of MailFlowRun

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/flows/{kind}/runs

POST/api/v1/mail/flows/{kind}mail.flow-savemail.write

Parameters

kindpathstring
kindpathstring
Idempotency-KeyheaderstringSee common parameters

Request body

MailFlowSave

Answer

MailFlow

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/flows/{kind}

GET/api/v1/mail/flowsmail.flowsmail.read

Answer

array of MailFlow

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/flows

POST/api/v1/mail/importsmail.importmail.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Request body

MailImportRequest

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/imports

POST/api/v1/mail/imports/previewmail.import-previewmail.read

Parameters

Idempotency-KeyheaderstringSee common parameters

Request body

MailImportRequest

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/imports/preview

GET/api/v1/mail/importsmail.importsmail.read

Answer

array of MailImport

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/imports

POST/api/v1/mail/kindsmail.kind-setmail.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Request body

MailKindSet

Answer

MailKind

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/kinds

GET/api/v1/mail/kindsmail.kindsmail.read

Answer

array of MailKind

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/kinds

POST/api/v1/mail/suppressions/{hash}/liftmail.lift-suppressionmail.write

Parameters

hashpathstring
hashpathstring
Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 404, 405, 409, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/suppressions/{hash}/lift

GET/api/v1/mail/mailings/{id}mail.mailingmail.read

Parameters

idpathstring
idpathstring

Answer

Mailing

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/mailings/{id}

GET/api/v1/mail/mailings/{id}/reportmail.mailing-reportmail.read

Parameters

idpathstring
idpathstring

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/mailings/{id}/report

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

limitqueryintegerThe 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.
afterquerystringSee 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

Parameters

streamquerystringThe stream: marketing or transactional.
atquerystringThe time the mail is due, in RFC 3339; now when left out.

Errors: 401, 403, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/mail/next-allowed

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.

countrequiredinteger
dkimrequiredstring
dmarcrequiredstring
iprequiredstring
spfrequiredstring
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.

maxinteger
mergeboolean
mininteger
namerequiredstring
requiredrequiredboolean
typerequiredstring
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.

contextsrequiredarray of string
fieldsrequiredarray of MailBlockField
kindrequiredstring
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.

kindsrequiredarray of MailBlockKind
limitsrequiredMailLimits
merge_fieldsrequiredarray 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.

daysrequiredarray of MailCalendarDay
monthrequiredstring
zonerequiredstring
MailCalendarDay

MailCalendarDay is one day of the calendar, as 2026-10-19.

daterequiredstring
flowsrequiredarray of MailCalendarFlow
mailingsrequiredarray of MailCalendarMailing
MailCalendarFlow

MailCalendarFlow is how many steps of a flow are due on a day.

duerequiredinteger
flowrequiredstring
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).

atrequiredstring (date-time)
idrequiredinteger
namerequiredstring
recipientsrequiredinteger
statusrequiredstring
topicrequiredstring
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_atrequiredstring (date-time)
emailrequiredstring
imported_atstring (date-time)
sourcerequiredstring
suppressedrequiredboolean
suppressed_reasonstring
topicsrequiredarray 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.

atrequiredstring (date-time)
statusrequiredstring
topicrequiredstring
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_marketingrequiredinteger
contactsrequiredinteger
suppressedrequiredinteger
withdrawnrequiredinteger
MailContactsPage

MailContactsPage is a page of the contacts, the totals of the store (the first page only), and where the next page starts.

contactsrequiredarray of MailContact
morerequiredboolean
nextrequiredstring
totalsMailContactTotals
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.

audiencestring
defaultboolean
due_next_24hrequiredinteger
enabledrequiredboolean
held_offstring
holdout_percentrequiredinteger
kindrequiredstring
reentry_daysrequiredinteger
runsrequiredmap of integer
stepsrequiredarray of MailFlowStep
topicrequiredstring
versionrequiredinteger
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.

convertedrequiredinteger
countedrequiredinteger
rate_permillerequiredinteger
revenuerequiredMoney
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_permillerequiredinteger
held_outrequiredMailFlowGroup
notestring
openrequiredinteger
restrequiredMailFlowGroup
rest_noterequiredstring
undecidablerequiredinteger
undecidable_whystring
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_atrequiredstring (date-time)
flowrequiredstring
held_outrequiredinteger
holdoutMailFlowHoldout
orders_notestring
runsrequiredmap of integer
stepsrequiredarray 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.

addressstring
endedstring (date-time)
exitstring
held_outboolean
idrequiredinteger
nextstring (date-time)
startedrequiredstring (date-time)
staterequiredstring
steprequiredinteger
triggerrequiredstring
versionrequiredinteger
withheldinteger
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).

documentsrequiredarray of any
enabledrequiredboolean
holdout_percentinteger
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.

afterrequiredstring
documentany
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.

bouncedrequiredinteger
clicksrequiredinteger
complaintsrequiredinteger
deliveredrequiredinteger
failedrequiredinteger
mails_clickedrequiredinteger
ordersrequiredinteger
queuedrequiredinteger
revenuerequiredMoney
sentrequiredinteger
steprequiredinteger
unsubscribesrequiredinteger
withheldrequiredinteger
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.

atrequiredstring (date-time)
byrequiredstring
file_namerequiredstring
idrequiredinteger
keptrequiredinteger
refusedrequiredinteger
rowsrequiredinteger
servicerequiredstring
skippedrequiredinteger
subscribedrequiredinteger
suppressedrequiredinteger
topicsrequiredarray of string
unchangedrequiredinteger
MailImportCounts

MailImportCounts are the rows of a file by outcome.

badrequiredinteger
keptrequiredinteger
skippedrequiredinteger
subscriberequiredinteger
suppressrequiredinteger
unchangedrequiredinteger
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.

columnsmap of string
statusesmap of string
topicsarray 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_rowsrequiredarray of MailImportRow
countsrequiredMailImportCounts
headerrequiredarray of string
pagerequiredarray of MailImportRow
rowsrequiredinteger
samplerequiredarray of string
status_valuesrequiredarray of MailImportStatusValue
unmappedrequiredarray 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.

filerequiredstring
file_namestring
limitinteger
mappingrequiredMailImportMapping
offsetinteger
servicerequiredstring
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.

emailrequiredstring
linerequiredinteger
outcomerequiredstring
reasonstring
tagsrequiredarray of string
topicsrequiredarray of string
MailImportStatusValue

MailImportStatusValue is a word of the status column and how many rows have it.

rowsrequiredinteger
wordrequiredstring
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_onrequiredboolean
always_on_whystring
changed_atstring (date-time)
changed_bystring
enabledrequiredboolean
kindrequiredstring
purposerequiredstring
sentrequiredstring
streamrequiredstring
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.

enabledrequiredboolean
kindrequiredstring
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.

blocksrequiredinteger
grid_leastrequiredinteger
grid_mostrequiredinteger
headingrequiredinteger
labelrequiredinteger
preheaderrequiredinteger
subjectrequiredinteger
textrequiredinteger
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_atrequiredstring (date-time)
atrequiredstring (date-time)
heldrequiredboolean
streamrequiredstring
wordsstring
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.

audienceinteger
audience_frozenboolean
cancelled_atstring (date-time)
createdrequiredstring (date-time)
documentrequiredany
held_bystring
held_untilstring (date-time)
held_whystring
idrequiredinteger
left_outMailingLeftOut
namerequiredstring
preparingboolean
progressrequiredMailingProgress
scheduled_bystring
segmentstring
send_atstring (date-time)
start_refusedrequiredarray of string
startedstring (date-time)
statusrequiredstring
subjectrequiredstring
topicrequiredstring
untracked_linksrequiredinteger
updatedrequiredstring (date-time)
viewstring
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_consentrequiredinteger
suppressedrequiredinteger
withdrewrequiredinteger
MailingLinkReport

MailingLinkReport is a link of a mailing and the clicks on it that were not automated.

clicksrequiredinteger
urlrequiredstring
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.

failedrequiredinteger
finish_atstring (date-time)
finish_lateboolean
queuedrequiredinteger
recipientsrequiredinteger
sentrequiredinteger
waitingrequiredinteger
withdrawninteger
withheldrequiredinteger
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.

bouncedrequiredinteger
clicksrequiredinteger
complaintsrequiredinteger
computed_atrequiredstring (date-time)
deliveredrequiredinteger
linksrequiredarray of MailingLinkReport
mailingrequiredinteger
mails_clickedrequiredinteger
moderequiredstring
ordersrequiredinteger
orders_noterequiredstring
revenuerequiredMoney
revenue_per_mailrequiredMoney
sentrequiredinteger
testMailingTestReport
unsubscribesrequiredinteger
untracked_linksrequiredinteger
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.

audienceinteger
audience_frozenboolean
cancelled_atstring (date-time)
idrequiredinteger
left_outMailingLeftOut
namerequiredstring
preparingboolean
segmentstring
statusrequiredstring
subjectrequiredstring
topicrequiredstring
updatedrequiredstring (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.

arequiredMailingVariantReport
brequiredMailingVariantReport
ends_atrequiredstring (date-time)
metricrequiredstring
minimumrequiredinteger
per_variantrequiredinteger
picked_atstring (date-time)
skippedrequiredboolean
skipped_whystring
tieboolean
too_fewboolean
too_few_whystring
winnerstring
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).

clicksrequiredinteger
ordersrequiredinteger
sentrequiredinteger
Money

Money is an amount: in minor units of its ISO 4217 currency, and as the store displays it.

currencyrequiredstring
displayrequiredstring
minorrequiredinteger
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.

addressstring
atrequiredstring (date-time)
hashrequiredstring
lifted_atstring (date-time)
mailinteger
reasonrequiredstring
registry_atstring (date-time)
SuppressionChange

SuppressionChange is what a lift did: whether it changed the suppression, and the suppression as it then stands.

changedrequiredboolean
suppressionrequiredSuppression

Made from engine/internal/openapi/openapi.json at commit 6c4cbd921. The contract-only operations come from the engine’s stub file, engine/internal/ops.