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.
| Input | Type | Required | Notes |
|---|---|---|---|
email | string | For updates. Omit to stay anonymous. | |
use_case | string | What mail, what you want done with it. | |
expected_volume | under_100_month, 100_1000_month, 1000_10000_month, over_10000_month, unknown | ||
price_band | free_only, pay_per_message, usd_10_25_month, usd_25_75_month, usd_75_200_month, usd_200_plus_month | What your user would pay for what they saw. | |
wants_beta | boolean | Default false. | |
wants_updates | boolean | Default false. | |
notes | string | Anything 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.
| Input | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
with_starters | boolean | Seed 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.
| Input | Type | Required | Notes |
|---|---|---|---|
label | string | yes | |
scopes | string[] | Default ["read","propose","run"]. | |
tenants | string[] | 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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}
| Input | Type | Required | Notes |
|---|---|---|---|
policy | object | yes |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
days | integer | Activity 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
name | string | yes | Unique within the tenant. |
description | string | ||
priority | integer | Lower runs first. Default 100. | |
enabled | boolean | ||
rule | any | A 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}}. | |
schema | string or object | A 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. | |
policy | object | {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 | |
destinations | string[] | 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. Bucket id or name |
name | string | Unique within the tenant. | |
description | string or null | ||
priority | integer or null | ||
enabled | boolean,null | ||
rule | object or null | ||
schema | object or null | ||
policy | object or null | ||
destinations | array or null | ||
force | boolean | Apply 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
request_exception | boolean | Default false. | |
reason | string | Why 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.
| Input | Type | Required | Notes |
|---|---|---|---|
confirm | boolean | yes | Must 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.
| Input | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
kind | named, relationship | Default "named". | |
local_part | string | For named addresses. | |
relationship_ref | string | Your own id for the relationship, for relationship addresses. | |
label | string | ||
daily_cap | integer | Messages per day before the address holds further mail. | |
bucket | string | Bucket 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.
| Input | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | ||
kind | named, relationship | ||
limit | integer | Default 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. Address id or local part |
enabled | boolean | yes |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. Address id or local part |
forwarders | string[] | 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.
| Input | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
kind | webhook, email | Default "webhook". | |
url | string | For kind webhook. | |
to | string | For 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. | |
secret | string | ||
enabled | boolean | Default true. | |
raw | url, inline, none | How 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_url | string | A 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. Destination id or name |
url | string | ||
to | string | For 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. | |
secret | string | ||
enabled | boolean | ||
raw | url, inline, none | How 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_url | string 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. Destination id or name |
code | string | yes |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
eml | string | Raw RFC 822 email text | |
envelope_from | string | The SMTP envelope sender, when you have it (e.g. an SRS-rewritten address); used to recognise automatic forwarding. | |
html | string | HTML to wrap as a message body when eml is not given | |
from | string | Sender for html ingest, e.g. 'Dana <dana@example.com>' | |
to | string | Recipient address; acts as the envelope recipient for rules like {address:'orders@'} | |
subject | string | ||
auth | object | Sandbox 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>.
| Input | Type | Required | Notes |
|---|---|---|---|
bucket | string | ||
status | string | ||
state | completed, incomplete | ||
limit | integer | Default 50. | |
before | string |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. |
include_headers | boolean | Default 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. |
reason | string |
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).
| Input | Type | Required | Notes |
|---|---|---|---|
mbox | string | An mbox file's text. | |
zip_base64 | string | A zip of .eml files, base64. | |
emls | string[] | Raw RFC 822 messages. | |
provenance | string | yes | Where these came from: a mailbox export, a date range, a person. |
candidate_days | integer | Default 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.
| Input | Type | Required | Notes |
|---|---|---|---|
tenant | string | Which 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.
| Input | Type | Required | Notes |
|---|---|---|---|
tenant | string | Which 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. | |
confirm | boolean | yes | You mean it. |
close_account | boolean | Also 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.
| Input | Type | Required | Notes |
|---|---|---|---|
hours | integer | Default 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.
| Input | Type | Required | Notes |
|---|---|---|---|
message_id | string | yes | |
bucket | string | yes | Bucket id or name the schema is for. Create it first with create_bucket if it does not exist. |
schema | object | yes | The 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}]}}} |
expected | object | field → 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. | |
note | string | ||
author | agent, hosted | Default "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.
| Input | Type | Required | Notes |
|---|---|---|---|
bucket | string | ||
status | pending, approved, rejected | ||
message | string | ||
limit | integer | Default 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. |
force | boolean | Apply even though existing cases fail. | |
note | string |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. |
reason | string | yes |
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).
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. Capture id |
field | string | yes | |
value | string | ||
near | integer | With 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. | |
span | object | ||
type | string, 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.
| Input | Type | Required | Notes |
|---|---|---|---|
bucket | string | ||
status | string | ||
message | string | ||
delivery | failed, delivered, none, undelivered | failed: 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) | |
limit | integer | Default 50. | |
before | string |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. |
field | string | yes | Path parameter. |
value | any | yes | |
reason | string |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. |
force | boolean | Default false. | |
note | string |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
status | open, resolved, dismissed | Default "open". | |
kind | string | ||
limit | integer | Default 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. |
status | resolved, dismissed | Default "resolved". | |
note | string |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
rule | any | yes | |
message_ids | string[] | ||
eml | string | ||
html | string |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
schema | object | yes | 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}]}}} |
message_ids | string[] | ||
eml | string | ||
html | string | ||
expected | object | message_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.
| Input | Type | Required | Notes |
|---|---|---|---|
capture_id | string | yes | |
expected | object | Field → expected value. Default: the capture's current values. | |
tricky | boolean | Mark as a hard case that is kept when the cap is reached. Default: true if the capture was changed or held for review. | |
note | string |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
bucket | string | Bucket id or name | |
include_retired | boolean | Default false. | |
limit | integer | Default 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.
| Input | Type | Required | Notes |
|---|---|---|---|
bucket | string | yes | Bucket id or name |
schema | object | A 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path 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.
| Input | Type | Required | Notes |
|---|---|---|---|
bucket | string | ||
limit | integer | Default 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.
| Input | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Path parameter. |
reason | string |
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.
| Input | Type | Required | Notes |
|---|---|---|---|
type | string | ||
subject_id | string | ||
after | string | ||
limit | integer | Default 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.
| Input | Type | Required | Notes |
|---|---|---|---|
text | string | yes | What happened and what you expected. |
about | string | The operation, page, or concept this is about, e.g. 'dry_run_schema' or 'docs/extractors'. | |
severity | low, normal, high | Default "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.