Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 7.5

C submission API

C Submission API
The most detailed of the five

The C submission binding is the fourth of five in the chapter: the same operations as in C++, but as functions with the common prefixes PmtaConn, PmtaMsg and PmtaRcpt in the headers submitter/PmtaConn.h, PmtaMsg.h and PmtaRcpt.h.

The difference is in object lifetime and errors: an object is allocated with an …Alloc function, initialized, and freed with …Free when done; functions return a success flag, and the reason is given by …GetLastError.

Connecting takes two functions: PmtaConnConnectRemote without login and PmtaConnConnectRemoteAuth with a login and password; the old PmtaConnConnect is deprecated.

The main trap is not checking the return value. The functions do not throw exceptions: an error is visible only by a FALSE return, and the object is unusable afterwards — it is freed and created anew.
What the Hub does. Not used: the Hub submits warm-up messages over SMTP.
Recommended values

The order of working with an object:

Step Connection Message
allocate PmtaConnAlloc PmtaMsgAlloc
initialize PmtaConnConnectRemote PmtaMsgInit
find out the error reason PmtaConnGetLastError PmtaMsgGetLastError
free PmtaConnFree PmtaMsgFree
The prefixes, headers, separation of allocation and initialization, freeing and the error query come from the manual (§ 7.5). The table is ours.
Example configuration
# connect to the node with a login and password
PmtaConn conn = PmtaConnAlloc();
PmtaConnConnectRemoteAuth(conn, "10.0.0.5", 25, "user", "secret");
A FALSE return is an error: the reason is given by PmtaConnGetLastError(conn), after which the connection is freed with PmtaConnFree.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
⇄

Related entries

3 relations

Does not work without

Object lifetime in the C bindingA related mechanism: they work together. § 7.5.1

Same name in other blocks

C++ submission APIThe same setting at another level. § 7.5

Where you can see it

Submission is a network service, and you can log into itA related mechanism: they work together. § 7.5.4

How to check on the node
Check that the binding headers are in place:
ls /opt/pmta/api/include/submitter/
The PmtaConn.h, PmtaMsg.h and PmtaRcpt.h files — the C binding is installed.
◇

What else to read

3 articles

◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.◇Headers the sender uses to control deliverySix 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.

In the Hub
Cost of a mistake
safe: a wrong value breaks nothing
Scenarios
Connect a sending platform