Knowledge base
from-domain<rewrite-list>DirectiveChanges the address domain in the From header — the one the recipient sees; this rule does not touch the envelope.html-edit-error-mode<signals>DirectiveRefuse delivery or send as is when HTML parsing failed; the default is to refuse.jobid-prefix<source>DirectiveThe value is prepended to the tag that arrived in the header; a reserved value substitutes the login of the submitting user.mail-from<rewrite-list>set by the HubDirectiveChanges the address from the SMTP MAIL FROM command — the one a bounce returns to and the one SPF checks; this rule does not touch the From header.process-x-job<source>set by the HubDirectiveA permission for the source: with it the header value becomes the message’s job tag, which is then used for selecting in the queue and for stopping a single mailing.add-date-header<source>DirectiveAdds a date to a message when the submitting side did not set one; the third value also rewrites an existing one.add-message-id-header<source>set by the HubDirectiveAdds an identifier to a message when the submitting side did not set one; an existing one is not rewritten.add-received-header<source>set by the HubDirectiveThe normal behavior of a mail server is to leave a mark in the transfer chain; it is turned off so that the recipient does not see where the message was submitted from.add-x-virtual-mta-header<source>DirectiveThe node itself signs the message with the name of the stream it went out through; the header reaches the recipient.allow-mailmerge<source>DirectiveOpens merge commands to the submitting side, with which one message is sent to many recipients with value substitution.bcc<source>DirectiveEvery message accepted from the source goes as a blind copy to the named address; the manual suggests this for archiving.engagement-tracking<signals>DirectiveThree values: do not collect, send the events yourself or let the engine insert links and pixels; the default is not to collect.host-idGlobalset by the HubDirectiveA per-server unique number that keeps two engine installations from producing the same Message-Id; the default of zero is the same for everyone.include-headers-fromGlobalDirectiveNames a file with headers in RFC 2822 format; they are inserted right after the Received header the node adds.jobid-header<source>DirectiveNames another message header from which the job label is taken; the usual method and the merge variable take precedence.pattern-list<source>set by the HubDirectiveAttaches a named rule list to the source; the list must be declared earlier in the file, and only one can be attached.remove-header<source>set by the HubDirectiveLists, separated by commas, the headers removed at delivery; an empty string erases the inherited list.rewrite-list<virtual-mta>DirectiveAttaches a named list; messages leaving through this sending address go through its rules.tracking-domain<signals>DirectiveThe domain that inserted links and pixels point to; the default is the vendor’s domain.bcc-upon-delivery<domain>DirectiveThe blind copy is taken on the recipient side and only from delivered messages; an empty string erases the inherited value.date-header-time<source>DirectiveChooses between the time the message was received and the time of actual delivery; applies only where the node adds the date itself.enable-bottom-open-pixel<signals>DirectiveThe switch for one of three kinds of insertion; works only with tracking done by the engine, on by default.enable-click-tracking<signals>DirectiveThe switch for one of three kinds of insertion; works only with tracking done by the engine, on by default.enable-top-open-pixel<signals>DirectiveThe switch for one of three kinds of insertion; works only with tracking done by the engine, on by default.macro-variables-preserve-case<domain>DirectiveApplies only to $to and $from: the recipient’s user name and domain are always lowercased.mailmerge-expands-undefined-variablesGlobalDirectiveWith the default an undefined variable turns into nothing; with the value false it stays in the message as is, brackets included.process-x-envid<source>DirectiveA permission for the source: with it the header value becomes the message’s envelope identifier and the header is removed; without it the header is ignored and stays in the message.replace-message-id-header<source>DirectiveRewrites an existing Message-Id with its own; has no effect at all on a message without an identifier.retain-x-dkim-options<source>DirectiveDecides whether the recipient will see the header with signing settings; the default is to remove it.retain-x-job<source>DirectiveDecides whether the recipient will see the job label; works only when reading the header is allowed and the header is present in the message.pickup-remove-dotGlobalDirectiveA concession to programs that escape a dot by SMTP rules where it is not required — in pickup directory files.Headers the sender uses to control deliverycriticalMechanismSix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.The node can insert pixels and rewrite links by itselfMechanismIn the vendor’s tracking mode the engine parses outgoing HTML, rewrites links to the tracking domain and inserts open pixels — with a choice of what to do if the markup cannot be parsed.Markup parsing and editingMechanismOpen and click tracking in sparkpost mode edits the message markup with the built-in gumbo-parser; by default a message whose markup could not be parsed is bounced.Personalization inside the engineMechanismVariables are set per recipient, and the node substitutes them at delivery — one submitted message goes to many recipients with different content.The HTTP submission formatMechanismInstead of a finished message, an HTTP request can carry the sender, subject, headers, text, HTML, AMP and attachments as separate fields — the node assembles and encodes the message itself.Numbered merge partsMechanismNumbered pieces of a message for multi-part merges: the first is implied, each number is used once.Encodings at submissionMechanismMessage data in a binding is added as 7-bit, 8-bit or base64: the first two do not change the data except for converting a lone LF to CRLF, base64 encodes on the fly; merge data supports only 7-bit and 8-bit.Date headerMechanismThe submission APIs can build a date header themselves for a message composed from scratch.<rewrite-list>Configuration blockA named list of rules; attached to a source by name, and all messages from there pass through it.