Inbound

Simulate an inbound email (test key)

Requires scope: send. Test key only (mk_test_…). Drives the receive/classify half of the product with a hand-supplied envelope: runs the real classifier, threads the message, persists a received row, and emits the same typed event + webhook a real inbound would. Set in_reply_to_message_id to a prior test-send id to simulate a reply.received. Send a whole email as raw_base64 (up to 3 MB) to test attachments: from, subject and body_text then default to the email's own.

post/v1/test/inbound

Request

  • Base URL: https://api.mails.ai
  • URL: https://api.mails.ai/v1/test/inbound
  • Auth: HTTP bearer

Request body

agentstring required

The agent that receives the message: its name or agt_ id. An agent the workspace does not have is a 404 agent_not_found, a key tied to another agent gets a 403, and a name two live agents share is a 409 agent_name_conflict.

fromstring email

Sender address. Required unless raw_base64 is sent, in which case it defaults to the raw email's From.

tostring

The address the message was sent to, kept as its delivered_to: any address real mail reaches this agent at (see the agent's receiving_address), such as the one a test signed up with. Left out, it is the agent's receiving_address. Any other address is a 400 invalid_param_value.

from_namestring

Sender display name, up to 256 characters. Left out, it is the raw email's From name when raw_base64 is sent; otherwise the message has none.

subjectstring

Subject line, up to 2,000 characters. Left out, it is the raw email's Subject when raw_base64 is sent; otherwise the message has none.

body_textstring

Message text. Required unless raw_base64 is sent, in which case it defaults to the raw email's text.

raw_base64string

A complete raw email (RFC 822), base64-encoded, up to 3 MB decoded. Its attachments become downloadable exactly as on real mail; from, subject and body_text default to the raw email's own.

in_reply_to_message_idstring

Id (msg_…) of one of this agent's sent messages, to simulate a reply to it. The message is then marked is_thread_reply and raises reply.received, unless spf and dkim are both fail. Left out, or naming any other message, it arrives as first contact.

spf'pass' | 'fail' | 'unknown'

Pretend SPF result, taken as given (default pass).

dkim'pass' | 'fail' | 'unknown'

Pretend DKIM result, taken as given (default pass). With spf, both fail simulates message.received.unauthenticated. Real mail gets that event when no DKIM signature aligned with the From domain verifies and the From domain's DMARC policy is quarantine or reject.

Response

The simulated inbound message and its classification.

message_idstring required

Id of the received message this call stored (rcv_…); read it at GET /v1/messages/received/{id}.

thread_idstring required

The thread the message was filed in (thrd_…), chosen as for real mail: that of the message named by in_reply_to_message_id when it is this agent's, else an open thread of the agent's with the same subject that the sender is already in, else a new one. It never joins a thread holding live mail.

event_idstring required

Id of the event this call raised (evt_…), sent to your webhooks with test_mode true; read it at GET /v1/events/{id}.

event_type'message.received' | 'reply.received' | 'message.received.unauthenticated' required

reply.received when in_reply_to_message_id named one of this agent's sent messages, message.received otherwise, and message.received.unauthenticated whenever spf and dkim are both fail.

quarantinedboolean required

True when classification.injection_score is 0.95 or more. The stored message then has parse_status quarantined.

test_modeboolean required

Always true: the message and its event are test mail, which is never billed.

has_attachmentboolean

True when the message carries at least one file attachment (embedded images do not count). Only a raw_base64 email can carry one.

Changes

No recorded changes to this operation across all 1 revision of this API.