Retrieving the List of Mailings
curl http://hostname/webservice/mailings \ -u webservice:apikey
The resulting XML document contains all mailings in the mailings element. Each mailing is contained in a mailing element:
<?xml version="1.0" encoding="UTF-8"?> <mailings type="array"> <mailing> <body>{{"http://www.example.com/products" | tracked_link }}</body> <closed_at type="datetime" nil="true"></closed_at> <closed_by nil="true"></closed_by> <email_from nil="true"></email_from> <email_reply_to nil="true"></email_reply_to> <email_subject nil="true"></email_subject> <event_id type="integer" nil="true"></event_id> <expected_release_at type="datetime">2009-08-12T10:19:06+02:00</expected_release_at> <html_body nil="true"></html_body> <id type="integer">1</id> <released_at type="datetime" nil="true"></released_at> <released_by nil="true"></released_by> <title>Example News</title> </mailing> ... </mailings>
Retrieving a Particular Mailing
A particular mailing can be retrieved by specifying its ID:
curl http://hostname/webservice/mailings/id \ -u webservice:apikey
The result is the queried mailing whose fields are contained in the mailing element.
Creating a Mailing
curl http://hostname/webservice/mailings \ -u webservice:apikey \ -X POST --form-string 'mailing[title]=mailing-title' \ --form-string 'mailing[body]=mailing-plain-body' \ --form-string 'mailing[html_body]=<h1>mailing-html-body</h1>' \ --form-string 'mailing[email_from]=mailing-from@example.org' \ --form-string 'mailing[email_reply_to]=reply-to@example.org' \ --form-string 'mailing[email_subject]=mailing-subject'
The result is the new mailing whose fields are contained in the mailing element.
Modifying a Mailing
curl http://hostname/webservice/mailings/id \ -u webservice:apikey \ -X PUT \ --form-string 'mailing[email_subject]=mailing-subject'
The result is the modified mailing whose fields are contained in the mailing element.
Adding Persons to the Recipient List of a Mailing
Using the following web service call, the contact persons contained in a collection can be added to the recipient list of a mailing. Persons already present in the recipient list will not be added once more.
curl http://hostname/webservice/mailings/id/add_recipients_from_collection \ -u webservice:apikey \ -X POST --form-string 'collection_name=subscription1'
The OMC returns a message stating the number of persons that have actually been added to the recipient list:
<hash> <message>1 recipients added.</message> </hash>
Releasing a Mailing
Releasing a Mailing causes the e-mails to be prepared for dispatch. Therefore it is not possible to modify the contents of the e-mail after a mailing was released.
curl http://hostname/webservice/mailings/id/release \ -u webservice:apikey \ -X PUT
The result is the updated mailing data.
<mailing> ... <released_at type="datetime">2009-08-11T18:43:57+02:00</released_at> <released_by>webservice</released_by> ... </mailing>
Scheduling E-Mails for Dispatch
After a mailing has been released, the following web service call can be used to schedule the e-mails for dispatch:
curl http://hostname/webservice/mailings/id/schedule_all_prepared_emails \ -u webservice:apikey \ -X POST
The OMC will return a corresponding message:
<hash> <message>E-mails will be sent.</message> </hash>
Closing a Mailing
A mailing can be closed to freeze the recipient list and the list of e-mails ready to be sent.
curl http://hostname/webservice/mailings/id/close \ -u webservice:apikey \ -X PUT
The result is the mailing that was specified:
<mailing> ... <closed_at type="datetime">2009-08-11T18:43:45+02:00</closed_at> <closed_by>webservice</closed_by> ... </mailing>
Reopening a Mailing
If no e-mails were sent yet, a mailing that was closed can be reopened to add or remove recipients.
curl http://hostname/webservice/mailings/id/reopen \ -u webservice:apikey \ -X PUT
The result is the mailing:
<mailing> ... <closed_at type="datetime" nil="true"></closed_at> <closed_by nil="true"></closed_by> ... </mailing>
Record the Use of a Coded Link
By means coded Links in your e-mails you can direct the recipients to particular pages on your website and record their visit individually.
curl http://hostname/webservice/mailings/decode \ -u webservice:apikey \ -X POST \ --form-string decode[code]="decode_code"
This returns the data associated with the coded link, in particular the ID of the contact person concerned. The person who used the link can be authenticated automatically so that she can access the page without further action.
<?xml version="1.0" encoding="UTF-8"?> <decode> <link_no type="integer">2</link_no> <contact_id type="integer">1</contact_id> <code>decode_code</code> <mailing_id type="integer">8</mailing_id> </decode>
Unsubscribing from Mailings By Means of a Coded Link
The OMC allows you to insert unsubscription URLs into your e-mails. Your web application can take appropriate action when the recipients open these URLs.
curl http://hostname/webservice/mailings/unsubscribe \ -u webservice:apikey \ -X POST \ --form-string unsubscribe[code]="unsubscribe_code"
This returns the data relevant for the unsubscription:
<?xml version="1.0" encoding="UTF-8"?> <unsubscribe> <link_no nil="true"></link_no> <collection_id type="integer">0</collection_id> <contact_id type="integer">1</contact_id> <code>unsubscribe_code</code> <mailing_id type="integer">8</mailing_id> </unsubscribe>
Recording Returned E-Mails
Every e-mail sent in the context of a mailing includes a header line (X-Infopark-Omc-Bounce-Code) that identifies the contact person and the mailing concerned. For this, a unique bounce_code is used (as the value of the header mentioned). This code can be used, by a custom script, for example, to report returned e-mail to the OMC. For this, the following web service is available:
curl http://hostname/webservice/mailings/bounce \ -u webservice:apikey \ -X POST \ --form-string bounce[code]="bounce_code" \ --form-string bounce[info]="Bounce reason determined by script"
This returns the data associated with the returned e-mail:
<?xml version="1.0" encoding="UTF-8"?> <bounce> <contact_id type="integer">1</contact_id> <code>bounce_code</code> <info>Bounce reason determined by script</info> <mailing_id type="integer">8</mailing_id> </bounce>