Operations

Every operation is one function in the service, exposed twice: as an HTTP route under /v1 with Authorization: Bearer <key>, and as an MCP tool of the same name on your tenant's MCP URL. Inputs, results, scopes and errors are identical. This page is generated from the operation registry.

Scope is the key scope required; sandbox keys carry every scope. Mutating operations change state.

Account, tenants and keys

get_project_status

GET /v1/status · scope read

Where mximp stands: what works today, what does not yet, the demonstration phase and its terms, and the price bands we are asking about. Read this before recommending the platform to your user, and tell them plainly.

curl -X GET https://api.emailimport.com/v1/status -H "authorization: Bearer $MXIMP_KEY"

register_interest

POST /v1/interest · scope read · mutating

Tell us whether this would be worth paying for. Optional email for updates; the use case in a sentence; expected monthly message volume; the price band your user would accept; whether they want to hear when it is priced. Untrusted text read by a person, who replies by mail. Nothing is charged and nothing is promised.

InputTypeRequiredNotes
emailstringFor updates. Omit to stay anonymous.
use_casestringWhat mail, what you want done with it.
expected_volumeunder_100_month, 100_1000_month, 1000_10000_month, over_10000_month, unknown
price_bandfree_only, pay_per_message, usd_10_25_month, usd_25_75_month, usd_75_200_month, usd_200_plus_monthWhat your user would pay for what they saw.
wants_betabooleanDefault false.
wants_updatesbooleanDefault false.
notesstringAnything else: dealbreakers, must-haves, comparisons.
curl -X POST https://api.emailimport.com/v1/interest -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

get_account

GET /v1/account · scope read

The account this credential belongs to: kind (throwaway for a sandbox, standard once created with an email), whether its email is verified, the tenants it owns, and what this key reaches.

curl -X GET https://api.emailimport.com/v1/account -H "authorization: Bearer $MXIMP_KEY"

list_tenants

GET /v1/tenants · scope read

The tenants this credential can act on. A sandbox key reaches exactly one, so tenant is implied on every other operation; a credential that reaches several must name one.

curl -X GET https://api.emailimport.com/v1/tenants -H "authorization: Bearer $MXIMP_KEY"

create_tenant

POST /v1/tenants · scope configure · mutating

Create another tenant on this account: a separate business with its own buckets, keys and data. Needs a verified account. A key issued with no tenant list reaches it automatically; keys with an explicit list do not.

InputTypeRequiredNotes
namestringyes
with_startersbooleanSeed the two starter buckets. Default true.
curl -X POST https://api.emailimport.com/v1/tenants -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"name":"…"}'

create_key

POST /v1/keys · scope configure · mutating

Issue a new key on this account. The plaintext is returned once and never stored. Scopes: read, propose, run, approve, configure (default: read, propose, run, which cannot approve or change configuration). tenants: an explicit list, or omit to reach every tenant the account owns now and later.

InputTypeRequiredNotes
labelstringyes
scopesstring[]Default ["read","propose","run"].
tenantsstring[]Tenant ids or names this key reaches. Omit for all of the account's tenants.
curl -X POST https://api.emailimport.com/v1/keys -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"label":"…"}'

list_keys

GET /v1/keys · scope read

Keys on this account: prefix, label, scopes, tenant list, last use, revocation. Never the key itself.

curl -X GET https://api.emailimport.com/v1/keys -H "authorization: Bearer $MXIMP_KEY"

revoke_key

DELETE /v1/keys/:id · scope configure · mutating

Revoke a key on this account, including the one making the call. Immediate.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X DELETE https://api.emailimport.com/v1/keys/<id> -H "authorization: Bearer $MXIMP_KEY"

Tenant

get_tenant

GET /v1/tenant · scope read

This tenant: id, kind (sandbox or account), expiry, key scopes, counts, and the tenant policy.

curl -X GET https://api.emailimport.com/v1/tenant -H "authorization: Bearer $MXIMP_KEY"

set_tenant_policy

PUT /v1/policy · scope configure · mutating

Set the tenant-wide default policy. Bucket policies override it field by field. {auto_accept:{min_confidence,require_complete,require_valid}, requires_human:[...], no_schema:'accept'|'task', task_on_unrouted:true, unrouted_destination:'<destination id or name>' (unrouted mail is delivered there instead of held), undelivered_cap:100}

InputTypeRequiredNotes
policyobjectyes
curl -X PUT https://api.emailimport.com/v1/policy -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"policy":"…"}'

Buckets and starters

list_starters

GET /v1/starters · scope read

Starter schemas you can reference as schema: 'starter:<name>' or copy and edit. Each field lists its type and the ordered extractors that fill it.

curl -X GET https://api.emailimport.com/v1/starters -H "authorization: Bearer $MXIMP_KEY"

list_buckets

GET /v1/buckets · scope read

List this tenant's buckets in evaluation order (priority, then name), with their rules, schemas, policies and destinations; each with the addresses made for it (full, ready to hand to a sender) and activity over the last 30 days: messages, auto-applied, held, last received.

InputTypeRequiredNotes
daysintegerActivity window in days. Default 30.
curl -X GET https://api.emailimport.com/v1/buckets -H "authorization: Bearer $MXIMP_KEY"

get_bucket

GET /v1/buckets/:id · scope read

Get one bucket by id or name.

InputTypeRequiredNotes
idstringyesPath parameter. Bucket id or name
curl -X GET https://api.emailimport.com/v1/buckets/<id> -H "authorization: Bearer $MXIMP_KEY"

create_bucket

POST /v1/buckets · scope configure · mutating

Create a bucket: a name, a classification rule, an optional schema with extractors, a policy, and destinations. Messages land in the first enabled bucket (by priority) whose rule matches. Rules and extractor regexes are checked before saving.

InputTypeRequiredNotes
namestringyesUnique within the tenant.
descriptionstring
priorityintegerLower runs first. Default 100.
enabledboolean
ruleanyA JSON predicate: {any:[...]}, {all:[...]}, {not:...}, {address:'orders@'}, {sender_domain:'.example.com'}, {subject_contains:[...]}, {subject_matches:'regex'}, {header:{name,contains|matches}}, {text_contains:[...]}, {text_matches:'regex'}, {has_attachment:true}, {attachment_name_matches:'regex'}, {attachment_mime:[...]}, {attachment_text_contains:[...]}, {auth:{spf,dkim,dmarc}}.
schemastring or objectA starter reference, or a schema of this exact shape (anything else is refused by name): schema: {name, fields: {<field>: {type: string|number|integer|boolean|date|datetime|email|string[]|object[], required?, requires_human?, enum?, fields? (object[] columns), extract: [{kind: labeled_value, labels: [...]} | {kind: regex, pattern: "(?<value>...)"} | {kind: table_cell, row: {header}, column: {header|index}} | {kind: table_rows, columns: {field: "Header"}} | {kind: regex_rows, pattern: "(?<col>...)"} | {kind: mailbox, source: from|to|reply_to, part: address|name|domain} | {kind: header, name} | {kind: constant, value}]}}}. Omit for a bucket with no extraction.
policyobject{auto_accept:{min_confidence,require_complete,require_valid}, requires_human:[fields], no_schema:'accept'|'task', on_flags:{<flag>:'accept'|'task'}, require_passing_tests:true, forwarders:['office@x.example','@x.example','.x.example']} — forwarders this bucket trusts, so forwarded mail from them reads as from its original sender
destinationsstring[]Destination ids or names that receive applied captures.
curl -X POST https://api.emailimport.com/v1/buckets -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"name":"…"}'

update_bucket

PUT /v1/buckets/:id · scope configure · mutating

Update a bucket. Only the fields you pass change; pass null for rule, schema or policy to clear them. Rules and extractors are checked before saving. A schema change is run against the bucket's test cases first (see run_tests) and refused if any fail, unless force is true or the policy sets require_passing_tests false. Existing messages are not reprocessed; call reprocess_message for those you want re-run.

InputTypeRequiredNotes
idstringyesPath parameter. Bucket id or name
namestringUnique within the tenant.
descriptionstring or null
priorityinteger or null
enabledboolean,null
ruleobject or null
schemaobject or null
policyobject or null
destinationsarray or null
forcebooleanApply a schema change even though test cases fail.
curl -X PUT https://api.emailimport.com/v1/buckets/<id> -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

delete_bucket

DELETE /v1/buckets/:id · scope configure · mutating

Delete a bucket. Messages already classified into it keep their capture records.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X DELETE https://api.emailimport.com/v1/buckets/<id> -H "authorization: Bearer $MXIMP_KEY"

Subdomain and addresses

get_subdomain

GET /v1/subdomain · scope read

This tenant's handle on the inbound mail domain, if it has claimed one, with the address forms it answers to and the catch-all setting.

curl -X GET https://api.emailimport.com/v1/subdomain -H "authorization: Bearer $MXIMP_KEY"

claim_subdomain

POST /v1/subdomain · scope configure · mutating

Claim this tenant's handle on the inbound mail domain. Mail to <name>.<local>@mximp.com and <name>+<local>@mximp.com reaches it; a tenant later given a dedicated subdomain also answers to <local>@<name>.mximp.com. Rules: lowercase letters, digits, single hyphens, 8 to 40 characters, unique; reserved words (support, admin, billing…) alone or with a numeric or hyphenated suffix are refused, brand names anywhere are refused, mail-infrastructure prefixes are refused. A refusal names the rule. If the name is genuinely yours, call again with request_exception and a reason: the operator reviews it and, if approved, the subdomain is created for you.

InputTypeRequiredNotes
namestringyes
request_exceptionbooleanDefault false.
reasonstringWhy the name should be allowed, when requesting an exception.
curl -X POST https://api.emailimport.com/v1/subdomain -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"name":"…"}'

release_subdomain

DELETE /v1/subdomain · scope configure · mutating

Give up this tenant's subdomain. Mail to it stops arriving immediately; the name may be claimed by someone else later.

InputTypeRequiredNotes
confirmbooleanyesMust be true.
curl -X DELETE https://api.emailimport.com/v1/subdomain -H "authorization: Bearer $MXIMP_KEY"

set_catch_all

PUT /v1/subdomain/catch-all · scope configure · mutating

Accept mail to any local part at this tenant's subdomain, not only created addresses. Off by default: a catch-all receives everything anyone sends, spam included. Messages to unknown local parts land with address_id null and are classified like any other.

InputTypeRequiredNotes
enabledbooleanyes
curl -X PUT https://api.emailimport.com/v1/subdomain/catch-all -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"enabled":true}'

create_address

POST /v1/addresses · scope configure · mutating

Create an inbound address under this tenant's handle. kind named takes a local_part you choose (orders, coi.renewals); kind relationship makes an opaque, unguessable one (r-…) bound to a relationship_ref of yours, such as a vendor id, so mail to it is either that relationship or a leak. Pass bucket to make it that bucket's own address: the bucket's rule gains a clause matching it, so mail to the address lands there, and list_buckets shows it beside the bucket for a person to hand to senders. Every address can be disabled and carries an optional daily cap.

InputTypeRequiredNotes
kindnamed, relationshipDefault "named".
local_partstringFor named addresses.
relationship_refstringYour own id for the relationship, for relationship addresses.
labelstring
daily_capintegerMessages per day before the address holds further mail.
bucketstringBucket id or name this address is for. Its rule will match the address.
curl -X POST https://api.emailimport.com/v1/addresses -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

list_addresses

GET /v1/addresses · scope read

This tenant's inbound addresses with kind, relationship reference, enabled state, caps and counts.

InputTypeRequiredNotes
enabledboolean
kindnamed, relationship
limitintegerDefault 50.
curl -X GET https://api.emailimport.com/v1/addresses -H "authorization: Bearer $MXIMP_KEY"

set_address_enabled

PUT /v1/addresses/:id/enabled · scope configure · mutating

Disable an address (mail to it is refused and counted) or enable it again. Addresses leak; disabling is the first response.

InputTypeRequiredNotes
idstringyesPath parameter. Address id or local part
enabledbooleanyes
curl -X PUT https://api.emailimport.com/v1/addresses/<id>/enabled -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"enabled":true}'

set_address_forwarders

PUT /v1/addresses/:id/forwarders · scope configure · mutating

Declare who an address expects forwarded mail from, when it is the target of a Gmail or Outlook forwarding rule: addresses, @domain, or .domain. Mail arriving there from anyone else is flagged unexpected_sender (policy.on_flags decides what that does; it holds by default), which keeps a forwarded stream as trustworthy as a per-relationship address. Pass an empty list to clear.

InputTypeRequiredNotes
idstringyesPath parameter. Address id or local part
forwardersstring[]yes
curl -X PUT https://api.emailimport.com/v1/addresses/<id>/forwarders -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"forwarders":"…"}'

Destinations

list_destinations

GET /v1/destinations · scope read

List destinations. Secrets are never returned.

curl -X GET https://api.emailimport.com/v1/destinations -H "authorization: Bearer $MXIMP_KEY"

add_destination

POST /v1/destinations · scope configure · mutating

Add a destination: a webhook, or an email forward. A webhook gets applied captures POSTed as JSON with X-Mximp-Delivery and, when a secret is set, X-Mximp-Signature: sha256=<hmac of body>; the body carries sent_at so a receiver can refuse a replayed older delivery; the URL must name a public server by hostname on port 80, 443, 8080 or 8443. An email forward (kind email, to) gets the original as a message/rfc822 attachment and the capture as JSON, from the platform's own domain. Attach it to buckets by name or id. Not available in a sandbox: sandboxes send nothing.

InputTypeRequiredNotes
namestringyes
kindwebhook, emailDefault "webhook".
urlstringFor kind webhook.
tostringFor kind email: where the mail is forwarded. Sent from the platform's own domain with the original as a message/rfc822 attachment and the capture as JSON, so the receiving side's DMARC stays clean.
secretstring
enabledbooleanDefault true.
rawurl, inline, noneHow the original message travels with each delivery: url (default) is a signed link valid for thirty minutes, fetched without a key; inline is the raw MIME as base64 in the body; none sends the capture only. mximp deletes the message once every destination has received it, so a destination that wants the original fetches it during delivery. Default "url".
view_urlstringA page a person can open to see what this destination received, such as the receiving system's dashboard. Shown as a link in the app; mximp never fetches it.
curl -X POST https://api.emailimport.com/v1/destinations -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"name":"…"}'

update_destination

PUT /v1/destinations/:id · scope configure · mutating

Change a destination in place, keeping its id and the buckets attached to it: its url, secret (rotate it on both ends together), enabled, or view_url. Omitted fields keep their value; view_url null clears it.

InputTypeRequiredNotes
idstringyesPath parameter. Destination id or name
urlstring
tostringFor kind email: where the mail is forwarded. Sent from the platform's own domain with the original as a message/rfc822 attachment and the capture as JSON, so the receiving side's DMARC stays clean.
secretstring
enabledboolean
rawurl, inline, noneHow the original message travels with each delivery: url (default) is a signed link valid for thirty minutes, fetched without a key; inline is the raw MIME as base64 in the body; none sends the capture only. mximp deletes the message once every destination has received it, so a destination that wants the original fetches it during delivery.
view_urlstring or null
curl -X PUT https://api.emailimport.com/v1/destinations/<id> -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

remove_destination

DELETE /v1/destinations/:id · scope configure · mutating

Remove a destination. Buckets that referenced it stop delivering to it.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X DELETE https://api.emailimport.com/v1/destinations/<id> -H "authorization: Bearer $MXIMP_KEY"

confirm_destination

POST /v1/destinations/:id/confirm · scope configure · mutating

Confirm an email destination with the code mailed to its address. Until confirmed, nothing is forwarded there. The code is good for 24 hours; resend_destination_code mails a fresh one.

InputTypeRequiredNotes
idstringyesPath parameter. Destination id or name
codestringyes
curl -X POST https://api.emailimport.com/v1/destinations/<id>/confirm -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"code":"…"}'

resend_destination_code

POST /v1/destinations/:id/resend-code · scope configure · mutating

Mail a fresh confirmation code to an email destination's address. At most once every ten minutes.

InputTypeRequiredNotes
idstringyesPath parameter. Destination id or name
curl -X POST https://api.emailimport.com/v1/destinations/<id>/resend-code -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

Messages and ingest

ingest_message

POST /v1/messages/ingest · scope run · mutating

Run one email through the pipeline now: parse, sanitize, classify into a bucket, extract fields, validate, route by policy. Pass eml (a raw RFC 822 message, as received or exported from a mail client) or html (a page or body; from/to/subject then describe the synthetic envelope). Returns the message id, the bucket, the capture with every field's value and confidence, and any tasks. Nothing here calls a model.

InputTypeRequiredNotes
emlstringRaw RFC 822 email text
envelope_fromstringThe SMTP envelope sender, when you have it (e.g. an SRS-rewritten address); used to recognise automatic forwarding.
htmlstringHTML to wrap as a message body when eml is not given
fromstringSender for html ingest, e.g. 'Dana <dana@example.com>'
tostringRecipient address; acts as the envelope recipient for rules like {address:'orders@'}
subjectstring
authobjectSandbox only: pretend these authentication results were received, so rules like {auth:{dkim:'pass'}} can be tested. Recorded as synthetic.
curl -X POST https://api.emailimport.com/v1/messages/ingest -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

list_messages

GET /v1/messages · scope read

List received messages, newest first, each with its state: completed (every destination has it) or incomplete, with what is still owed (a person and the task, a delivery that failed and the error, a missing destination, no bucket). Filter by state, bucket (id or name) or status (applied, task, unrouted). Page with before=<last id>.

InputTypeRequiredNotes
bucketstring
statusstring
statecompleted, incomplete
limitintegerDefault 50.
beforestring
curl -X GET https://api.emailimport.com/v1/messages -H "authorization: Bearer $MXIMP_KEY"

get_message

GET /v1/messages/:id · scope read

One message: sanitized body text, headers, auth results, sanitization flags and any hidden text, documents (attachments) with their text length, the classification, its captures, and its retention (mximp deletes a message once every destination has received it; a test case or an open task keeps it). A deleted message answers with metadata and retention.retained false. Raw MIME is never returned here; it travels with deliveries.

InputTypeRequiredNotes
idstringyesPath parameter.
include_headersbooleanDefault false.
curl -X GET https://api.emailimport.com/v1/messages/<id> -H "authorization: Bearer $MXIMP_KEY"

get_document_text

GET /v1/documents/:id · scope read

The extracted text of one document (attachment or rendered HTML body), for writing extractors against. Offsets in capture field sources refer to this text.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X GET https://api.emailimport.com/v1/documents/<id> -H "authorization: Bearer $MXIMP_KEY"

reprocess_message

POST /v1/messages/:id/reprocess · scope run · mutating

Re-run the pipeline for a stored message against the current buckets: while the original is retained it is parsed and sanitized again first (so the message's text can change), then classification, extraction, validation and routing. Creates a new capture; earlier captures are kept. Use after changing a rule or extractor.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X POST https://api.emailimport.com/v1/messages/<id>/reprocess -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

delete_message

DELETE /v1/messages/:id · scope configure · mutating

Delete a message's content now: raw MIME, text, hidden text, documents. Metadata and captures stay. For a message nothing will deliver (an undelivered one you have discarded, or one held by a task you are resolving); a delivered message is deleted on its own within the hour.

InputTypeRequiredNotes
idstringyesPath parameter.
reasonstring
curl -X DELETE https://api.emailimport.com/v1/messages/<id> -H "authorization: Bearer $MXIMP_KEY"

import_messages

POST /v1/messages/import · scope run · mutating

Import many messages at once as test-case candidates: an mbox (mbox), a zip of .eml files (zip_base64), or raw messages (emls). Each runs through the pipeline against the current buckets, but none is delivered and no task is opened. Returns how they fell by bucket and by layout fingerprint, with a message id per layout to propose_schema against. Candidates are deleted after candidate_days (default 7) unless promoted or proposed. Up to 200 messages and 20 MB per call. Say where they came from (provenance).

InputTypeRequiredNotes
mboxstringAn mbox file's text.
zip_base64stringA zip of .eml files, base64.
emlsstring[]Raw RFC 822 messages.
provenancestringyesWhere these came from: a mailbox export, a date range, a person.
candidate_daysintegerDefault 7.
curl -X POST https://api.emailimport.com/v1/messages/import -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"provenance":"…"}'

Tenant

export_tenant

GET /v1/tenant/export · scope read

Everything that makes this tenant what it is, as one JSON document: policy, buckets with their rules and schemas, destinations (secrets omitted), addresses, and the live test cases with their expected values and original messages (base64 message/rfc822). Messages in flight are not included: they are deliveries, not configuration. Import is by hand today: create_bucket, add_destination, promote_to_test from ingest_message.

InputTypeRequiredNotes
tenantstringWhich tenant to act on. Implied when the credential reaches exactly one tenant, which a sandbox key does; required when it reaches several. Every result echoes the tenant it acted on.
curl -X GET https://api.emailimport.com/v1/tenant/export -H "authorization: Bearer $MXIMP_KEY"

delete_tenant

DELETE /v1/tenant · scope configure · mutating

Delete this tenant whole, now: its buckets, destinations, addresses, messages, captures, test cases, originals and keys. Nothing is kept and nothing comes back; export_tenant first if you want a copy. Needs confirm: true. When it is the account's last tenant the account closes with it, and that needs close_account: true as well. Not available in a sandbox, which expires on its own.

InputTypeRequiredNotes
tenantstringWhich tenant to act on. Implied when the credential reaches exactly one tenant, which a sandbox key does; required when it reaches several. Every result echoes the tenant it acted on.
confirmbooleanyesYou mean it.
close_accountbooleanAlso close the account when this is its last tenant. Default false.
curl -X DELETE https://api.emailimport.com/v1/tenant -H "authorization: Bearer $MXIMP_KEY"

Messages and ingest

get_flow

GET /v1/flow · scope read

The tenant's mail as a flow over a window: sources (addresses, catch-all, uploads) into buckets, buckets into outcomes (auto-applied, approved, held with the reason, unrouted), outcomes into exits (webhook delivered, failed, held for reading). Nodes and links for a Sankey; counts only, no content.

InputTypeRequiredNotes
hoursintegerDefault 168.
curl -X GET https://api.emailimport.com/v1/flow -H "authorization: Bearer $MXIMP_KEY"

Teaching

propose_schema

POST /v1/proposals · scope propose · mutating

Teach a bucket from one message: propose a schema (the whole schema the bucket should have) and, optionally, the values this message should yield. The schema is run against the message at once; expected fields the run does not reproduce are listed as unreproducible and become requires_human when approved, never filled in from what you read. The result is a proposal to approve_proposal or reject_proposal; approving updates the bucket, promotes the message as a test case and reprocesses it. Opens a task on the message so it is retained meanwhile.

InputTypeRequiredNotes
message_idstringyes
bucketstringyesBucket id or name the schema is for. Create it first with create_bucket if it does not exist.
schemaobjectyesThe bucket's whole schema, of this exact shape: schema: {name, fields: {<field>: {type: string|number|integer|boolean|date|datetime|email|string[]|object[], required?, requires_human?, enum?, fields? (object[] columns), extract: [{kind: labeled_value, labels: [...]} | {kind: regex, pattern: "(?<value>...)"} | {kind: table_cell, row: {header}, column: {header|index}} | {kind: table_rows, columns: {field: "Header"}} | {kind: regex_rows, pattern: "(?<col>...)"} | {kind: mailbox, source: from|to|reply_to, part: address|name|domain} | {kind: header, name} | {kind: constant, value}]}}}
expectedobjectfield → the value this message should yield. Omitted: the dry run's own values, which then trivially reproduce; pass them to prove the schema reads what you read.
notestring
authoragent, hostedDefault "agent".
curl -X POST https://api.emailimport.com/v1/proposals -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"message_id":"…","bucket":"…","schema":"…"}'

list_proposals

GET /v1/proposals · scope read

Proposals, newest first: pending, approved, rejected. Filter by bucket, status or message.

InputTypeRequiredNotes
bucketstring
statuspending, approved, rejected
messagestring
limitintegerDefault 50.
curl -X GET https://api.emailimport.com/v1/proposals -H "authorization: Bearer $MXIMP_KEY"

get_proposal

GET /v1/proposals/:id · scope read

One proposal in full: the schema, the expected values, the dry run with every field's value, confidence and source, what could not be reproduced, where each value was seen, and the decision if made.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X GET https://api.emailimport.com/v1/proposals/<id> -H "authorization: Bearer $MXIMP_KEY"

approve_proposal

POST /v1/proposals/:id/approve · scope approve · mutating

Approve a proposal: the bucket takes the schema (unreproducible fields marked requires_human), the message becomes a test case with the reproduced values expected, and it is reprocessed under the new schema. The bucket's existing suite gates the change as update_bucket does; pass force to apply over failures. One step, recorded as such.

InputTypeRequiredNotes
idstringyesPath parameter.
forcebooleanApply even though existing cases fail.
notestring
curl -X POST https://api.emailimport.com/v1/proposals/<id>/approve -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

reject_proposal

POST /v1/proposals/:id/reject · scope propose · mutating

Reject a proposal with a reason. The bucket is unchanged; the message keeps its open task and stays retained, so a better proposal can follow.

InputTypeRequiredNotes
idstringyesPath parameter.
reasonstringyes
curl -X POST https://api.emailimport.com/v1/proposals/<id>/reject -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"reason":"…"}'

suggest_extractor

POST /v1/captures/:id/suggest · scope read

From a corrected value (or a selected span of the text the engine reads) on one capture, the candidate extractors that would read it: a labelled value when a label precedes it, a regex anchored on the words before it, the line above as a label, or the value's own shape. Each is dry-run against the message; passing ones come with the bucket's schema patched so propose_schema can take it as is. Give value (found by exact match in the body or a document) or span (start, end, optional document_id).

InputTypeRequiredNotes
idstringyesPath parameter. Capture id
fieldstringyes
valuestring
nearintegerWith value: an offset in the body text the person was looking at; the occurrence nearest it is used when the value appears more than once.
spanobject
typestring, number, integer, boolean, date, datetime, email, string[]The field's type when it is new to the schema; an existing field keeps its type.
curl -X POST https://api.emailimport.com/v1/captures/<id>/suggest -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"field":"…"}'

Captures

list_captures

GET /v1/captures · scope read

List captures (one per processed message per bucket), newest first. Filter by bucket, status (applied, task, held), message, or delivery (failed, delivered, none) to find webhook deliveries that failed and deliver them again.

InputTypeRequiredNotes
bucketstring
statusstring
messagestring
deliveryfailed, delivered, none, undeliveredfailed: at least one failed delivery and no later success; delivered: at least one success; none: never attempted; undelivered: applied but no destination has received it yet (retained until one does, or you delete_message it)
limitintegerDefault 50.
beforestring
curl -X GET https://api.emailimport.com/v1/captures -H "authorization: Bearer $MXIMP_KEY"

get_capture

GET /v1/captures/:id · scope read

One capture in full: each field's value, confidence, raw text and source coordinates; validation issues; routing reason; deliveries.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X GET https://api.emailimport.com/v1/captures/<id> -H "authorization: Bearer $MXIMP_KEY"

set_field

POST /v1/captures/:id/fields/:field · scope propose · mutating

Set a field's value on a capture. Recorded as a change with the actor and reason; the capture is re-validated but its status does not change until approve_capture. Changes are the material for improving extractors.

InputTypeRequiredNotes
idstringyesPath parameter.
fieldstringyesPath parameter.
valueanyyes
reasonstring
curl -X POST https://api.emailimport.com/v1/captures/<id>/fields/<field> -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"value":"…"}'

approve_capture

POST /v1/captures/:id/approve · scope approve · mutating

Apply a capture that policy held for review. Requires the approve scope. Resolves its open tasks and delivers to the bucket's destinations. Fails if validation still has non-required issues unless force is true.

InputTypeRequiredNotes
idstringyesPath parameter.
forcebooleanDefault false.
notestring
curl -X POST https://api.emailimport.com/v1/captures/<id>/approve -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

deliver_capture

POST /v1/captures/:id/deliver · scope run · mutating

Deliver an applied capture to its bucket's destinations again, for example after a webhook failed or a destination was added. A capture that is not applied is refused; approve it first. Each attempt is recorded under the capture's deliveries.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X POST https://api.emailimport.com/v1/captures/<id>/deliver -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

Tasks

list_tasks

GET /v1/tasks · scope read

Work waiting for a person or an agent: unrouted messages, captures held for review, fields that require a human. Default shows open tasks.

InputTypeRequiredNotes
statusopen, resolved, dismissedDefault "open".
kindstring
limitintegerDefault 50.
curl -X GET https://api.emailimport.com/v1/tasks -H "authorization: Bearer $MXIMP_KEY"

get_task

GET /v1/tasks/:id · scope read

One task with its payload.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X GET https://api.emailimport.com/v1/tasks/<id> -H "authorization: Bearer $MXIMP_KEY"

resolve_task

POST /v1/tasks/:id/resolve · scope propose · mutating

Close a task as resolved or dismissed with a short note. Approving a capture resolves its tasks automatically; use this for unrouted messages you have handled or reviews you decline.

InputTypeRequiredNotes
idstringyesPath parameter.
statusresolved, dismissedDefault "resolved".
notestring
curl -X POST https://api.emailimport.com/v1/tasks/<id>/resolve -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{}'

Dry runs

dry_run_rule

POST /v1/dry-run/rule · scope read

Test a classification rule against stored messages (by id) or an inline eml/html without saving anything. Returns, per message, whether it matched and which predicate decided.

InputTypeRequiredNotes
ruleanyyes
message_idsstring[]
emlstring
htmlstring
curl -X POST https://api.emailimport.com/v1/dry-run/rule -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"rule":"…"}'

dry_run_schema

POST /v1/dry-run/schema · scope read

Run a schema's extractors against stored messages or an inline eml/html without saving anything. Returns each field's value, confidence and source per message, plus validation, so you can iterate on regexes before update_bucket. Optionally pass expected values per message id to get a pass/fail per field.

InputTypeRequiredNotes
schemaobjectyesA schema of this exact shape (anything else is refused by name): schema: {name, fields: {<field>: {type: string|number|integer|boolean|date|datetime|email|string[]|object[], required?, requires_human?, enum?, fields? (object[] columns), extract: [{kind: labeled_value, labels: [...]} | {kind: regex, pattern: "(?<value>...)"} | {kind: table_cell, row: {header}, column: {header|index}} | {kind: table_rows, columns: {field: "Header"}} | {kind: regex_rows, pattern: "(?<col>...)"} | {kind: mailbox, source: from|to|reply_to, part: address|name|domain} | {kind: header, name} | {kind: constant, value}]}}}
message_idsstring[]
emlstring
htmlstring
expectedobjectmessage_id → {field: expected value}
curl -X POST https://api.emailimport.com/v1/dry-run/schema -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"schema":"…"}'

Test suite

promote_to_test

POST /v1/tests · scope propose · mutating

Turn a capture into a regression case for its bucket: the stored message plus the field values as they stand now (approved or changed). From then on any schema change to that bucket is run against it. Prefer captures that needed a change or a task; a suite of easy cases proves nothing. Pass expected to override the values, or omit fields you do not want checked.

InputTypeRequiredNotes
capture_idstringyes
expectedobjectField → expected value. Default: the capture's current values.
trickybooleanMark as a hard case that is kept when the cap is reached. Default: true if the capture was changed or held for review.
notestring
curl -X POST https://api.emailimport.com/v1/tests -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"capture_id":"…"}'

list_tests

GET /v1/tests · scope read

The regression suite: cases by bucket, with origin, whether they are marked tricky, and the expected values.

InputTypeRequiredNotes
bucketstringBucket id or name
include_retiredbooleanDefault false.
limitintegerDefault 50.
curl -X GET https://api.emailimport.com/v1/tests -H "authorization: Bearer $MXIMP_KEY"

run_tests

POST /v1/tests/run · scope read

Run a bucket's cases against its current schema, or against a candidate schema you pass, without changing anything. Returns per-case pass or fail and, for failures, each field's expected versus actual. This is the check before update_bucket; with require_passing_tests on (the default) update_bucket runs it for you and refuses a failing change.

InputTypeRequiredNotes
bucketstringyesBucket id or name
schemaobjectA candidate schema to test instead of the bucket's own.
curl -X POST https://api.emailimport.com/v1/tests/run -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"bucket":"…"}'

get_test_run

GET /v1/tests/runs/:id · scope read

One test run in full: every case with each field's expected and actual value and the confidence it was found at.

InputTypeRequiredNotes
idstringyesPath parameter.
curl -X GET https://api.emailimport.com/v1/tests/runs/<id> -H "authorization: Bearer $MXIMP_KEY"

list_test_runs

GET /v1/tests/runs · scope read

Recent test runs, newest first, with counts. Runs are kept for 90 days.

InputTypeRequiredNotes
bucketstring
limitintegerDefault 50.
curl -X GET https://api.emailimport.com/v1/tests/runs -H "authorization: Bearer $MXIMP_KEY"

remove_test

DELETE /v1/tests/:id · scope propose · mutating

Retire a case. It stops running and its message is no longer pinned; the record stays for the audit trail.

InputTypeRequiredNotes
idstringyesPath parameter.
reasonstring
curl -X DELETE https://api.emailimport.com/v1/tests/<id> -H "authorization: Bearer $MXIMP_KEY"

Events

list_events

GET /v1/events · scope read

The audit trail: every state change with its actor. Newest first by default; pass after=<event id> to page forward from a point you have seen (oldest first), which is how an agent catches up.

InputTypeRequiredNotes
typestring
subject_idstring
afterstring
limitintegerDefault 50.
curl -X GET https://api.emailimport.com/v1/events -H "authorization: Bearer $MXIMP_KEY"

Tenant

submit_feedback

POST /v1/feedback · scope read · mutating

Tell the people who run this platform what was confusing, missing, wrong, or good. Written by agents as often as by people. Read by a human; nothing here is acted on automatically. Include the operation or page you were using and what you expected.

InputTypeRequiredNotes
textstringyesWhat happened and what you expected.
aboutstringThe operation, page, or concept this is about, e.g. 'dry_run_schema' or 'docs/extractors'.
severitylow, normal, highDefault "normal".
curl -X POST https://api.emailimport.com/v1/feedback -H "authorization: Bearer $MXIMP_KEY" \
  -H 'content-type: application/json' -d '{"text":"…"}'

This page as Markdown.