The principle of scenarios
A scenario sends a sequence of emails to contacts entering a hosted database. Each trigger pairs a campaign with a delay, counted from the moment the contact is recorded. Three triggers set to 0 days, 3 days and 10 days produce a three-message sequence, with no further intervention.
What the API does, and what it does not
This is the part to understand before writing any code: the API does not orchestrate scenarios, it feeds them.
The scenario itself is built in the MDWorks interface. The hosted database, the campaigns, the triggers and their delays are all defined there, and no SOAP endpoint creates or modifies them. Your information system does not drive the sending logic, it injects recipients into it.
This split has a practical consequence. Changing a sequence, adding a follow-up message or adjusting a delay all happen in the interface, without touching your code. Conversely, a misconfigured scenario produces nothing visible on the API side: the insertion succeeds, and no email goes out.
What must exist before your first call
Three items, in this order:
- The campaigns, created under “Automation”, “Email campaigns”. They are built like a regular message, with one difference: recipients cannot be edited, since it is the scenario trigger that imports them.
- The hosted database, with complex queries enabled. If the database does not appear when you create the scenario, that setting is almost always the reason. It sits in the “Structure” section of the database.
- The scenario and at least one trigger. A scenario without a trigger exists, accepts recipients, and sends nothing.
The interface side is covered in Create a scenario.
The two available functions
| Function | Purpose | Return value |
|---|---|---|
Envoi_Mail_Scenario_API | Inserts a recipient into the loop and starts the countdown | The recipient identifier, useful for tracking, or an array containing the error message |
Liste_Destinataires_Scenario | Reads back the recipients already present in a scenario | An array of email addresses |
Both go through the control endpoint, https://www.eml-srv.com/_soap/control.php, and authenticate with the account login and password.
Envoi_Mail_Scenario_API also accepts the personalization variables nom, prenom and p1 to p6. They belong to the recipient, so they are available across every campaign in the sequence, not just the first one.
What happens after the insertion
The countdown starts at insertion, not at scenario creation. Each trigger then fires at its own delay. A trigger set to 0 days and 0 hours sends its campaign immediately after the contact is recorded.
Two safeguards apply before insertion. An address that has already unsubscribed, and therefore sits in your blacklist, is rejected with an explicit message. A syntactically invalid address is rejected too. In both cases the function returns an error array rather than an identifier, which remains the simplest way to tell a success from a rejection on the calling side.
The log of messages actually sent is available in the interface, under the “History” section of the scenario.