Submit

Submit message for delivery

Submit message for delivery. If reference message ID is provided then EmailEngine adds all headers and flags required for a reply/forward automatically.<br/><br/>Delivery is asynchronous. A 2xx means the message was queued, not that it was sent. Failed attempts are retried with exponential backoff up to the configured deliveryAttempts; follow the outcome through the Outbox endpoints or the messageSent, messageDeliveryError and messageFailed webhooks.<br/><br/>For SMTP accounts EmailEngine uploads the sent message to the Sent Mail folder after delivery. Gmail API and MS Graph accounts file sent messages themselves, so no upload is performed.

post/v1/account/{account}/submit

Request

  • Base URL: https://your-emailengine-host
  • URL: https://your-emailengine-host/v1/account/{account}/submit
  • Auth: HTTP bearer

Path parameters

accountstring required

Unique identifier for the email account

Example:user123

Query parameters

useStructuredFormatboolean

For MS Graph accounts: send as structured JSON instead of raw MIME

Headers

x-ee-timeoutinteger

Request timeout in milliseconds. Raises the command timeout above the EENGINE_TIMEOUT default for a long-running request; a value below the default has no effect

Example:30000
idempotency-keystring

Unique key to prevent duplicate processing of the same request

Example:submit-12345

Request body

subjectstring

Email subject line

textstring

Plain text message content

htmlstring

HTML message content

previewTextstring

Preview text shown in email clients after the subject line

templatestring

Stored template ID to load the email content from

rawstring

A Base64-encoded email message in RFC 822 format

messageIdstring

Message ID

headersCustomHeaders

Custom Headers

trackOpensboolean

Should EmailEngine track opens for this message

trackClicksboolean

Should EmailEngine track clicks for this message

copyboolean nullable

If set then either copies the message to the Sent Mail folder or not. If not set then uses the account's default setting

sentMailPathstring

Upload sent message to this folder. By default the account's Sent Mail folder is used.

localestring

Optional locale

tzstring

Optional timezone

sendAtstring date-time

Send message at specified time

deliveryAttemptsinteger

How many delivery attempts to make until message is considered as failed

gatewaystring

Optional SMTP gateway ID for message routing

listIdstring

List ID for Mail Merge. Must use a subdomain name format. Lists are registered ad-hoc, so a new identifier defines a new list.

baseUrlstring

Optional base URL for trackers. This URL must point to your EmailEngine instance.

proxystring

Optional proxy URL to use when connecting to the SMTP server. A token with restricted permissions can not set this - it redirects a session that carries the account credentials

localAddressstring

Optional local IP address to bind to when connecting to the SMTP server

dryRunboolean

If true, then EmailEngine does not send the email and returns an RFC822 formatted email file. Tracking information is not added to the email.

Example request

{
  "to": [
    {
      "name": "Nyan Cat",
      "address": "nyan.cat@example.com"
    }
  ],
  "subject": "What a wonderful message!",
  "text": "Hello from myself!",
  "html": "<p>Hello from myself!</p>",
  "attachments": [
    {
      "filename": "transparent.gif",
      "content": "R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=",
      "contentType": "image/gif"
    }
  ]
}

Response

Returns the queue ID the message was accepted under. Delivery happens asynchronously - a 200 means queued, not sent.

responsestring
messageIdstring

Message-ID header value. Not present for bulk messages.

queueIdstring

Queue identifier for scheduled email. Not present for bulk messages.

sendAtstring date-time

Scheduled send time

previewstring

Base64 encoded RFC822 email if a preview was requested. Not returned for mail-merge submissions.

Example response

{
  "response": "Queued for delivery",
  "messageId": "<a2184d08-a470-fec6-a493-fa211a3756e9@example.com>",
  "queueId": "d41f0423195f271f",
  "sendAt": "2021-07-08T07:06:34.336Z",
  "reference": {
    "message": "AAAAAQAACnA",
    "threadId": "1694936993596975454",
    "success": true,
    "error": "Referenced message was not found"
  },
  "preview": "Q29udGVudC1UeXBlOiBtdWx0aX...",
  "idempotency": {
    "key": "submit-12345",
    "status": "MISS"
  },
  "mailMerge": [
    {
      "success": true,
      "to": {
        "name": "Andris 2",
        "address": "andris@ethereal.email"
      },
      "messageId": "<19b9c433-d428-f6d8-1d00-d666ebcadfc4@ekiri.ee>",
      "queueId": "1812477338914c8372a",
      "sendAt": "2021-07-08T07:06:34.336Z"
    }
  ]
}

Changes

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