POST /api/inject/v1

Note

This page was generated by extracting information from a JSON Schema data file for the API. It may be missing some information, or otherwise suggest approximate or placeholder values based on information in the schema file; this is due to limitations on how that data is extracted from the underlying Rust code and into the JSON Schema, and then again from there and into these docs.

Inject a message using a given message body, with template expansion, to a list of recipients.

Request Body

The request body is required.

The Content-Type header must be set to application/json.

This is an object value, with the following properties:

• content - required Content. The message content. Can either be a fully formed MIME message, or a json object describing the MIME structure that should be created.

• deferred_generation - optional boolean. When set to true, the injection request will be queued and the actual generation and substitution will happen asynchronously with respect to the injection request.

• deferred_spool - optional boolean. When set to true, the message will not be written to the spool until it encounters its first transient failure. This can improve injection rate but introduces the risk of loss of accountability for the message if the system were to crash before the message is delivered or written to spool, so use with caution!

• envelope_sender - required string. Specify the envelope sender that will be sent in the MAIL FROM portion of SMTP.

• recipients - required array of Recipient. The list of recipients

• substitutions - optional object. When using templating, this is the map of placeholder name to replacement value that should be used by the templating engine. This map applies to all recipients, with the per-recipient substitutions taking precedence.

• template_dialect - optional TemplateDialectWithSchema.

• trace_headers - optional HttpTraceHeaders.

Examples

{
  "content": "From: user@example.com\nSubject: Hello\n\nHello there",
  "deferred_generation": false,
  "deferred_spool": false,
  "envelope_sender": "some.id@bounces.sender-example.com",
  "recipients": [
    {
      "email": "john.smith@mailbox-example.com",
      "name": "John Smith",
      "substitutions": {
        "age": 42,
        "gender": "male"
      }
    }
  ],
  "substitutions": {
    "campaign_title": "Fall Campaign"
  },
  "template_dialect": "Jinja",
  "trace_headers": {
    "header_name": "string",
    "include_meta_names": [
      "string"
    ],
    "received_header": false,
    "supplemental_header": false
  }
}

Responses

Status 200

Message(s) injected successfully

Content-Type: application/json

This is an object value, with the following properties:

• errors - required array of string. The list of error messages

• fail_count - required integer. The number of messages that failed to inject

• failed_recipients - required array of string (email). The list of failed recipients

• success_count - required integer. The number of messages that were injected successfully

Examples

{
  "errors": [
    "string"
  ],
  "fail_count": 42,
  "failed_recipients": [
    "user@example.com"
  ],
  "success_count": 42
}