Knowledge base
total-max-smtp-outGlobalcriticalset by the HubDirectiveKicks in first if a queue limit is higher; on a Standard license — silently.virtual-mta<virtual-mta-pool>criticalset by the HubDirectiveThe line lists a sending address in a pool; without a number the members are used round-robin, with a number — in the given proportion, and the shares must add up to 100.max-memory-usage-percentGlobalDirectiveWhen the share of physical memory is exceeded, the node responds 452 to MAIL FROM until usage drops back below it.min-free-space<spool>set by the HubDirectiveWhen free space falls below the threshold, the directory stops accepting mail; when space comes back, receiving resumes by itself.spool-max-recipientsGlobalDirectiveLimits how many recipients the node holds in queues; above the ceiling, submission is refused with a temporary error. The default is to calculate from the machine’s resources.max-message-size<source>set by the HubDirectiveWithout the line the size is not limited at all — the engine’s default is “unlimited.”priority<spool>DirectiveDirectories with a higher priority are always used until they fill up; with equal priority they alternate.dummy-smtp-await-slotGlobalDirectiveWait for a slot or reply 421 at once — and 421 changes the behavior of the sending side.dummy-smtp-has-chunkingGlobalDirectiveThe default is not to announce it, and then the run uses a different transfer method than production mail will.dummy-smtp-has-pipeliningGlobalDirectiveOf the three lines in the set, this one affects the figure the most: without pipelining the conversation is several times longer.dummy-smtp-has-verpGlobalDirectiveNeeded exactly when mail with unique return addresses is run.dummy-smtp-ipGlobalDirectiveA local address keeps the black hole inside the machine; an external one opens it to the network.dummy-smtp-latencyGlobalDirectiveZero by default — and with zero the run measures the wrong thing: a real receiver never answers instantly.dummy-smtp-portGlobalDirectiveThe default of zero means “do not listen”: until the port is set, there is no mechanism.dummy-smtp-update-statsGlobalDirectiveOn by default — and it is the only line in the family that spoils production data.thread-reuseGlobalDirectiveTurning it off makes the engine discard threads immediately; this costs performance and removes a workaround for an old library bug. The default depends on the platform.add-x-msys-api-header<domain>DirectiveAdds the service header that sets SparkPost options and carries the job label into it as the campaign name; a header already in place is left untouched.add-x-msys-api-header-metadata<domain>DirectiveCarries the content of the named headers into the service header; does not work without the parent line, with the header already in place, or for headers the node adds itself.sparkpost-ip-pool<domain>DirectiveNames an address pool on the service’s side; the addresses themselves are not yours, and their reputation is shared with the service’s other customers.sparkpost-sandbox<domain>DirectivePasses the sandbox option to SparkPost: the message goes out from a SparkPost test domain without your own sending domain, and according to the SparkPost documentation an account gets no more than five such messages.thread-max-priorityGlobalDirectiveSets the fast end of the priority range the engine’s threads run with; a Unix-only directive, paired with the lowest one.thread-min-priorityGlobalDirectiveSets the slow end of the priority range the engine’s threads run with; a Unix-only directive, paired with the highest one.Different domains in one queue, because the gateway is the samecriticalMechanismDomains whose lowest-priority MX records match the list are combined into one queue and limited as a single receiver.External addresses on one machine, nodes insidecriticalMechanismNodes sit on internal addresses and go out through a proxy that holds all the external sending addresses.A group of sending addresses with traffic sharesMechanismA named group of sending addresses; without shares messages are distributed in rotation, with shares in the given proportion, in steps of a tenth of a percent.How to turn a sending plan into hardwareMechanismTwo constants for sizing any node: about 2 KB of memory per queued recipient and spool space proportional to the total size of the messages.Cloud restrictionsMechanismClouds restrict outbound mail on port 25 until you ask them to lift the limit, and mailbox providers treat their address ranges with suspicion.The activation key is a prerequisite for installation, not a step after itMechanismWithout an activation key from SparkPost support the engine neither installs nor runs, and the license tier sets the outbound connection ceiling: on Standard everything above 200 is ignored.Exposing metrics to a collectorMechanismExposing the node’s metrics to an external collector in its format.What makes a virtual machine riskyMechanismRunning on a virtual machine is possible, but the manual does not recommend it without sufficient hardware and properly tuned hypervisor settings: under load the node may stop responding.A license for a fleet, not for a serverMechanismThe license is not bound to a server: it is installed on as many machines as the instance limit allows, and the nodes send volume statistics to the vendor every hour.A fake receiver inside the node itselfMechanismThe node listens on its own port and pretends to be someone else’s server: messages go nowhere, but the load is real.Prepare a machine for the enginecriticalProcedureFive requirements and a supported operating system must be in place before installation: a static address with a name, a reachable resolver, synchronized time, sized hardware and a license key.Introducing a new address with part of someone else's trafficcriticalProcedureA warmed-up address hands its partner the first messages of the day to each receiver; the counters reset at midnight and survive a restart.show licenseCommandPrints the license details: product, version, platform, licensee, serial number, issue and expiry dates.The whole node state in one documentcriticalAPI endpointReturns the status page as a structure in XML or JSON: product, license, machine, traffic, connections, resolver, queues, spool and the running flag — in one response.ConnectionsMetricThe number of simultaneous connections: now, the maximum and the allowed limit, in both directions.Traffic countersMetricRecipients, messages and kilobytes for all time, for the last hour and for the last minute.Spool filesMetricThe number of spool files in use.Spool capacityMetricHow many recipients the spool holds now and how many it can hold at most.Throughput peaksMetricThe highest values per hour and per minute — recipients, messages, kilobytes.