Deliver one message to one or more recipients of a single domain.

POST

/v1/messages

const url = 'https://idmx.example.org/v1/messages';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    Signature: 'example',
    'Signature-Input': 'example',
    'Content-Digest': 'example',
    'Content-Type': 'multipart/mixed'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://idmx.example.org/v1/messages \
  --header 'Content-Digest: example' \
  --header 'Content-Type: multipart/mixed' \
  --header 'Idempotency-Key: example' \
  --header 'Signature: example' \
  --header 'Signature-Input: example'

One POST per recipient domain. The body is sent once; the response carries one result per recipient (mirrors SMTP RCPT semantics).

The receiver SHOULD validate as much as possible synchronously (recipient exists, quota, policy) before returning 2xx. Failures after acceptance are reported as an RFC 3464 DSN delivered as a normal message.

Body: multipart/mixed with exactly two parts, in order: part 1 application/json envelope, part 2 message/rfc822 raw message bytes (no transfer encoding). See delivery.md §2.

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters /^[A-Za-z0-9._~-]+$/

Covers the whole delivery (all recipients). Retries re-sign with a fresh timestamp but reuse the same key. Receivers remember keys for at least 7 days, scoped per signing domain. Same key with different content -> idempotency_conflict. See delivery.md §4.

Signature

required

string

RFC 9421 signature. Profile in signing.md.

Signature-Input

required

string

RFC 9421 signature parameters (created, keyid, covered components). Profile in signing.md.

Content-Digest

required

string

RFC 9530 digest of the request body, covered by the signature.

Request Body^required

multipart/mixed

object

envelope

required

Structured delivery envelope (delivery.md §3). Unknown fields MUST be ignored (leaves room for later capabilities such as sender attestations).

object

from

required

One of:

string
null

<local-part>@<domain>, split at the last @. Domain in host-name syntax (IDNA A-labels). Local-part as written in SMTP (RFC 5321/6531 dot-string or quoted-string), at most 64 octets, in minimal form: the pattern does not check the octet limit or that a quoted-string’s content is not a dot-string. See delivery.md §3.1.

string

<= 320 characters /^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~\u00A0-\uFFFF-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~\u00A0-\uFFFF-]+)*|"(?:[ !#-\[\]-~\u00A0-\uFFFF]|\\["\\])*")@[A-Za-z0-9.-]+$/

required

Recipients; all MUST share one domain. At most max_recipients.

Array<string>

>= 1 items unique items

key

additional properties

any

message

required

Opaque RFC 5322/MIME message, byte-for-byte. DKIM signatures inside survive.

string

Responses

200

The request itself was acceptable; see per-recipient results (always 200, even if every recipient is rejected). A retried delivery with a known Idempotency-Key returns the original response.

application/json

Per-recipient outcomes (delivery.md §5.2).

object

results

required

One entry per envelope recipient, same order as to.

Array<object>

object

recipient

required

string

<= 320 characters /^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~\u00A0-\uFFFF-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~\u00A0-\uFFFF-]+)*|"(?:[ !#-\[\]-~\u00A0-\uFFFF]|\\["\\])*")@[A-Za-z0-9.-]+$/

status

required

accepted; rejected (permanent, never retry, never SMTP fallback); deferred (temporary, retry as a new delivery). Senders MUST treat unknown values as deferred.

string

problem

REQUIRED unless status is accepted.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

retry_after

Seconds; only meaningful with deferred.

integer

key

additional properties

any

key

additional properties

any

Example

{
  "results": [
    {
      "status": "accepted",
      "problem": {
        "type": "https://idmx-project.org/problems/invalid_request"
      }
    }
  ]
}

400

RFC 9457 problem details. Semantics per type in errors.md.

application/problem+json

RFC 9457 problem details. type is https://idmx-project.org/problems/<identifier>.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

Example

{
  "type": "https://idmx-project.org/problems/invalid_request"
}

401

RFC 9457 problem details. Semantics per type in errors.md.

application/problem+json

RFC 9457 problem details. type is https://idmx-project.org/problems/<identifier>.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

Example

{
  "type": "https://idmx-project.org/problems/invalid_request"
}

403

RFC 9457 problem details. Semantics per type in errors.md.

application/problem+json

RFC 9457 problem details. type is https://idmx-project.org/problems/<identifier>.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

Example

{
  "type": "https://idmx-project.org/problems/invalid_request"
}

404

RFC 9457 problem details. Semantics per type in errors.md.

application/problem+json

RFC 9457 problem details. type is https://idmx-project.org/problems/<identifier>.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

Example

{
  "type": "https://idmx-project.org/problems/invalid_request"
}

409

RFC 9457 problem details. Semantics per type in errors.md.

application/problem+json

RFC 9457 problem details. type is https://idmx-project.org/problems/<identifier>.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

Example

{
  "type": "https://idmx-project.org/problems/invalid_request"
}

413

RFC 9457 problem details. Semantics per type in errors.md.

application/problem+json

RFC 9457 problem details. type is https://idmx-project.org/problems/<identifier>.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

Example

{
  "type": "https://idmx-project.org/problems/invalid_request"
}

429

RFC 9457 problem details with retry hint.

application/problem+json

RFC 9457 problem details. type is https://idmx-project.org/problems/<identifier>.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

Example

{
  "type": "https://idmx-project.org/problems/invalid_request"
}

Headers

Retry-After

string

503

RFC 9457 problem details with retry hint.

application/problem+json

RFC 9457 problem details. type is https://idmx-project.org/problems/<identifier>.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

Example

{
  "type": "https://idmx-project.org/problems/invalid_request"
}

Headers

Retry-After

string

default

RFC 9457 problem details. Semantics per type in errors.md.

application/problem+json

RFC 9457 problem details. type is https://idmx-project.org/problems/<identifier>.

object

type

required

string format: uri

title

string

status

integer

detail

string

instance

string

versions

REQUIRED in unsupported_version problems, absent otherwise: all major versions this receiver serves, as in the capabilities document (discovery.md §5.1).

Array<string>

unique items

key

additional properties

any

Example

{
  "type": "https://idmx-project.org/problems/invalid_request"
}

Deliver one message to one or more recipients of a single domain.

Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

409

Example

413

Example

429

Example

Headers

503

Example

Headers

default

Example

Request Body^required