Mailboxes
Messages

Inject a sandbox inbound message

Create a fake inbound message in isolated sandbox storage. This endpoint requires a test API key. It runs the normal inbound threading, rule, and webhook pipeline without delivering mail to any supplied address.

post/mailboxes/{id}/sandbox/inbound

Request

  • Base URL: https://shipmail.to/api/v1
  • URL: https://shipmail.to/api/v1/mailboxes/{id}/sandbox/inbound
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://shipmail.to/api/auth/oauth2/authorize, token URL https://shipmail.to/api/auth/oauth2/token)

Headers

Idempotency-Keystring

Unique key for idempotent requests. Printable ASCII, 1-255 characters. The response is cached for 24 hours. A message send also derives the message ID from the key, so after the cache expires a retry on the same endpoint returns the message already sent, without comparing the body, for as long as that message exists.

X-Shipmail-Organizationstring

OAuth access tokens only. The organization ID this request acts on. Required when the OAuth connection was approved for several organizations (400 validation_error without it); optional with one. An organization the connection was not approved for returns 403 authorization_error. Ignored for API keys, which belong to one organization.

Request body

subjectstring required
textstring

Plain text body. At least one of text or html is required.

htmlstring

HTML body. At least one of text or html is required.

message_idstring
in_reply_tostring
referencesstring[]
received_atstring date-time

Response

Sandbox inbound message created.

object'message' required
idstring required
mailbox_idstring required
thread_idstring nullable required

Deprecated and not stable: a legacy thread ID that changes when the mail server re-threads its IDs or a relayed send's placeholder key is replaced. It remains supported in thread paths; store conversation_id instead.

conversation_idstring nullable required

Stable Shipmail conversation identifier (thd_...). Store this: it survives thread merges and mail-server re-threading, which thread_id does not.

source_rfc_message_idstring nullable required

Source RFC Message-ID supplied by the caller or observed before relay.

delivered_rfc_message_idstring nullable required

Exact provider-assigned delivered RFC Message-ID after Shipmail observes it in a recipient reply. Null before an observation and never reconstructed from the SES provider ID.

client_referencestring nullable required

Caller-defined organization-scoped reference.

metadataMessageMetadata required

Up to 20 scalar values and 8 KB of JSON. Nested objects and arrays are rejected.

subjectstring nullable required
from_addressstring nullable required
source'api' | 'dashboard' | 'newsletter' | 'inbound' | 'smtp' | 'assistant' required
mode'live' | 'test' required

The API-key data plane that owns this resource. Test resources are isolated from live delivery, quota, suppression, and reputation.

status'scheduled' | 'queued' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'cancelled' required
scheduled_atstring date-time nullable required

UTC ISO 8601 time when a scheduled message should be sent. Null for immediate messages.

created_atstring date-time required
updated_atstring date-time required

Changes

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