API Methods

Here are the methods supported by the API grouped by the primary entity they operate on.

system methods

system.listMethods()

List system methods. Part of XML-RPC introspection.

Returns:Returns a list of method names.
Return type:array
system.methodHelp(method)

Gets help about a method. Part of XML-RPC introspection.

Parameters:method (string) – method name
Returns:Returns a text describing the method.
Return type:string
Raises:6002: No such method
system.multicall(calls)

Run a batch/multicall XML-RPC request with multiple XML-RPC calls.

Parameters:calls (array) – An array of structs with the XML-RPC calls according to the spec (with keys: methodName, params)
Returns:An array of mixed types according to the return values of the calls
Return type:array
Raises:Any fault the embedded calls may raise.
Raises:9992: Invalid multicall call struct
Raises:9993: Recursive multicall not allowed

Note

This is an extension to the XMLRPC specification.

  • Please refer to http://mirrors.talideon.com/articles/multicall.html for details.
  • This implementation of system.multicall doesn’t allow recursive calls. Those will return the 9993 fault code.
  • The calls may be executed out of order, but the results will be in order (the calls are made concurrently on the server side).
  • A maximum of 50 calls may be executed at once. Larger batches will raise 9992.
  • The above faults are all reported on their respective call in the calls array as reflected in the returned array. Exception: If the calls parameter is not of the array type, a “global” fault with code 9992 will be returned.

subscription methods

mailer.cancel_all_subscriptions(email_address)

Cancel all subscriptions for a given subscriber.

Parameters:email_address (string) – The e-mail address of the subscriber.
Returns:True on success.
Return type:boolean
Raises:1001: Invalid e-mail address
mailer.cancel_subscription(email_address, lists)

Cancel a subscription for the lists specified.

Parameters:
  • email_address (string) – The address of the subscriber
  • lists (array) – A list of mailinglist IDs
Returns:

True on success.
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1002: The user is not subscribed
Raises:

2001: Invalid mailing list

Note

If the user was not subscribed some of the lists, the NotSubscribed fault is raised.

mailer.course_force_stage(subscriber, list, stage)

Forces the subscriber to the specified stage on the course of the list.

Parameters:
  • subscriber (string) – The e-mail address of a subscriber.
  • list (integer) – A mailing list ID.
  • stage (integer) – An integer ID of a stage on the mailing list.
Returns:

True on success.
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1002: The user is not subscribed
Raises:

2001: Invalid mailing list
Raises:

2003: Invalid stage.
Raises:

2005: Invalid operation on archived list
mailer.course_next_stage(subscriber, list)

Advances the subscriber to the next stage on the course of the list.

Parameters:
  • subscriber (string) – The e-mail address of a subscriber.
  • list (integer) – A mailing list ID.
Returns:

True on success.
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1002: The user is not subscribed
Raises:

2001: Invalid mailing list
Raises:

2002: The course has already ended (no stage to advance to)
Raises:

2005: Invalid operation on archived list
mailer.create_subscription(email_address, lists, optin)

Create a subscription for the lists specified.

Parameters:
  • email_address (string) – The address of the subscriber
  • lists (array) – A list of mailinglist IDs
  • optin (boolean) – Should we send a optin e-mail
Returns:

True on success.
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1003: The user is already subscribed
Raises:

1011: New subscriptions blocked for your account
Raises:

2001: Invalid mailing list
Raises:

2004: Opt-in not configured (on one or more lists).
Raises:

2005: Invalid operation on archived list
mailer.create_subscription_error(email_address, optin)

Get a detailed error description for any 1001 errors encountered during subscription processing.

Parameters:
  • email_address (string) – The address of the subscriber
  • optin (boolean) – Does the new subscription require opt-in? (for stop list checking)
Returns:

A string describing the error. Will be empty for success.
Return type:

string
mailer.create_subscription_with_data(email_address, lists, optin, data)

Create a subscription for the lists specified with data from the data struct.

Parameters:
  • email_address (string) – The e-mail address of the subscriber
  • lists (array) – A list of mailing list IDs
  • optin (boolean) – Should we send a optin e-mail
  • data (struct) – A struct of subscriber data, see Subscriber data
Returns:

True on success.
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1003: The user is already subscribed
Raises:

1004: Invalid data field
Raises:

1011: New subscriptions blocked for your account
Raises:

2001: Invalid mailing list
Raises:

2004: Opt-in not configured (on one or more lists).
Raises:

2005: Invalid operation on archived list
mailer.delete_subscriber(email_address)

Note

This method is an alias for: ubivox.cancel_all_subscriptions()

Retrieve the consent details for any active subscription by a subscriber.

Parameters:
  • subscriber (string) – The e-mail address of a subscriber.
  • list (integer) – A mailing list ID.
Returns:

Consent details.
Return type:

string
Raises:

1001: Invalid e-mail address
Raises:

1002: The user is not subscribed
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
mailer.has_active_subscription(email_address, list)

Check if a given e-mail address has an active subscription on a given list

Parameters:
  • email_address (string) – The address of the subscriber
  • list (integer) – A mailing list ID.
Returns:

True if found, false if not.
Return type:

boolean
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
mailer.list_subscriptions(list, offset)

Retrieve the first 1000 subscribers from the offset specified, ordered by time added.

Parameters:
  • list (integer) – A mailing list ID.
  • offset (integer) – (0-indexed) Offset.
Returns:

A list structs of subscriptions:

  • subscriber: Email address of the subscriber.
  • data: A struct of subscriber data, see Subscriber data
  • state: The subscription state. One of the following: pending (Pending end-user authorization), active (Active and receiving deliveries), suspended (Suspended due to bounces), unsubscribed (Unsubscribed by user), removed (Unsubscribed by client), deleted (Deleted)
  • added: When was the subscription added
  • activated: When was the subscription added
  • unsubscribed: When was the subscription cancelled
  • suspended: When was the subscription suspended
  • test_recipient: A boolean indicating if the subscriber is a test recipient on this list
Return type:

array
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

5003: Invalid offset

Note

Subscribers may appear more than once if they have a history of older subscriptions.

mailer.remove_all_subscriptions(email_address)

Remove all subscriptions for a given subscriber (administrative unsubscription).

Parameters:email_address (string) – The e-mail address of the subscriber.
Returns:True on success.
Return type:boolean
Raises:1001: Invalid e-mail address
mailer.remove_subscription(email_address, lists)

Remove a subscription for the lists specified (administrative unsubscription).

Parameters:
  • email_address (string) – The address of the subscriber
  • lists (array) – A list of mailinglist IDs
Returns:

True on success.
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1002: The user is not subscribed
Raises:

2001: Invalid mailing list

Note

If the user was not subscribed some of the lists, the NotSubscribed fault is raised.

Updates the consent details for any active subscription by a subscriber.

Parameters:
  • subscriber (string) – The e-mail address of a subscriber.
  • list (integer) – A mailing list ID.
  • consent_details (string) – The consent details
Returns:

True on success
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1002: The user is not subscribed
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
mailer.set_subscription_reference(subscriber, list, reference)

Updates the reference field for a given subscription.

Parameters:
  • subscriber (string) – The e-mail address of a subscriber.
  • list (integer) – A mailing list ID.
  • reference (string) – The reference to be used.
Returns:

True on success.
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1002: The user is not subscribed
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
mailer.set_subscription_testrecipient(subscriber, list, test_recipient)

Updates the subscription with test recipient status.

Parameters:
  • subscriber (string) – The email address of a subscriber.
  • list (integer) – A mailing list ID.
  • test_recipient (boolean) – A boolean indicating if the subscriber should receive tests.
Returns:

True on success.
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1002: The user is not subscribed
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list

subscriber methods

mailer.forget_subscriber(subscriber, data)

Invoke the EU GDPR Right To Be Forgotten for a subscriber.

Parameters:
  • subscriber (string) – The e-mail address of the existing subscriber
  • data (list) – A list of any data field keys potentially containing PII that needs to be cleared
Returns:

True on success
Return type:

boolean
Raises:

1009: Invalid subscriber

Note

The data parameter may also use a couple of special values: Use the string all to clear all data fields. Or null or an empty list to not clear any.

mailer.get_stopped_subscribers()

Retrieve a list of stopped subscribers.

Returns:A list of structs representing deliveries this subscriber has received:
  • email: The e-mail address of the subscriber.
  • cause: The cause of the entry on the stop list, see Stoplist causes.
  • stopped: When was the stop list entry added.
Return type:array
mailer.get_stopped_subscribers_since(since)

Retrieve a list of stopped subscribers.

Parameters:since (string) – Return only stopped subscribers since (YYYY-MM-DD HH:MM:SS).
Returns:A list of structs representing deliveries this subscriber has received:
  • email: The e-mail address of the subscriber.
  • cause: The cause of the entry on the stop list, see Stoplist causes.
  • stopped: When was the stop list entry added.
Return type:array
Raises:5001: Invalid date/time format
mailer.get_subscriber(subscriber)

Fetches information about a given subscriber.

Parameters:subscriber (string) – The e-mail address of a subscriber.
Returns:A struct of:
  • subscriptions: A list of structs:
    • list_title: Mailing list title
    • list_id: Mailing list ID
    • state: The subscription state. One of the following: pending (Pending end-user authorization), active (Active and receiving deliveries), suspended (Suspended due to bounces), unsubscribed (Unsubscribed by user), removed (Unsubscribed by client), deleted (Deleted)
    • added: When was the subscription added
    • activated: When was the subscription added
    • unsubscribed: When was the subscription cancelled
    • suspended: When was the subscription suspended
    • test_recipient: A boolean indicating if the subscriber is a test recipient on this list
  • data: A struct of subscriber data, see Subscriber data
Return type:struct
Raises:1001: Invalid e-mail address
mailer.get_subscriber_delivery_stats(subscriber)

Fetches delivery statistics for a given subscriber.

Parameters:subscriber (string) – The e-mail address of a subscriber.
Returns:A list of structs representing deliveries this subscriber has received:
  • list_id: The maillist ID
  • list_title: The maillist title
  • delivery_id: The delivery ID
  • delivery_subject: The delivery ID
  • delivery_send_time: The delivery send time
  • read: Has the subscriber read this newsletter?
  • clicked: Has the subscriber clicked this newsletter?
Return type:array
Raises:1001: Invalid e-mail address

Note

Entries may be delayed for up to 24 hours after a delivery has been sent.

mailer.list_all_subscribers()

Retrieve all subscribers (up to 10000 only).

Returns:A list e-mail-adresses.
Return type:array
mailer.list_all_subscribers_with_data()

Retrieve all subscribers (up to 10000 only).

Returns:A list of structs of:
  • email: E-mail address of the subscriber
  • data: Data associated with the subscriber, see Subscriber data
Return type:array
mailer.list_subscribers(offset)

Retrieve the first 50 subscribers from the offset specified.

Parameters:offset (integer) – (0-indexed) Offset.
Returns:A list e-mail-adresses.
Return type:array
Raises:5003: Invalid offset
mailer.list_subscribers_with_data(offset)

Retrieve the first 50 subscribers from the offset specified.

Parameters:offset (integer) – (0-indexed) Offset.
Returns:A list of structs of:
  • email: E-mail address of the subscriber
  • data: Data associated with the subscriber, see Subscriber data
Return type:array
Raises:5003: Invalid offset
mailer.set_subscriber_data(subscriber, data)

Updates the subscribers data.

Parameters:
  • subscriber (string) – The email address of a subscriber.
  • data (struct) – A struct of subscriber data, see Subscriber data
Returns:

True on success.
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1004: Invalid data field
mailer.stop_subscriber(subscriber)

Add a subscriber to the stop list by administrative request.

Parameters:subscriber (string) – The email address of a subscriber.
Returns:True on success.
Return type:boolean
Raises:1001: Invalid e-mail address
mailer.update_subscriber_email(subscriber, new_email, responsible_user, consent)

Update the e-mail address of an existing subscriber

Parameters:
  • subscriber (string) – The e-mail address of the existing subscriber
  • new_email (string) – The new e-mail address
  • responsible_user (integer) – The ID of the Ubivox user responsible for this change (for logging purposes).
  • consent (boolean) – Has the subscriber given consent to this change (must be true)
Returns:

True on success
Return type:

boolean
Raises:

1001: Invalid e-mail address
Raises:

1003: The user is already subscribed
Raises:

1009: Invalid subscriber
Raises:

1010: Missing consent
Raises:

5013: Invalid user

delivery methods

mailer.copy_delivery(delivery, new_subject, new_maillist)

Make a copy of a (sent or draft) delivery.

Parameters:
  • delivery (integer) – ID of the delivery.
  • new_subject (string) – Subject of the delivery.
  • new_maillist (integer) – ID of the maillist, which the new delivery will be placed on.
Returns:

The ID of the new delivery.
Return type:

integer
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
mailer.create_delivery(subject, html_body, text_body, list)

Create a new delivery for the the specified list.

Parameters:
  • subject (string) – Subject for the delivery.
  • html_body (string) – The HTML body of the delivery including logic for merging.
  • text_body (string) – The text body of the delivery including logic for merging.
  • list (integer) – The mailing list to be used. (integer ID)
Returns:

The new delivery ID on success.
Return type:

integer
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

3004: Problem with delivery content
Raises:

5014: Invalid subject
mailer.delete_delivery(delivery)

Deletes a delivery and everything related to it (statistics, …).

Parameters:delivery (integer) – ID of the delivery.
Returns:True on success.
Return type:boolean
Raises:2005: Invalid operation on archived list
Raises:3001: Invalid delivery
mailer.get_delivery(delivery)

Get information about a delivery.

Parameters:delivery (integer) – ID of the delivery.
Returns:A struct of:
  • id: Id of the delivery.
  • subject: Subject of the delivery.
  • send_time: The send time of the delivery (if available)
  • html_body: The HTML body of the delivery including logic for merging.
  • text_body: The text body of the delivery including logic for merging.
  • archive_html_body: The HTML body of an archive version of the newsletter.
  • list: The maillist to be used. (integer ID)
  • state: Delivery state. One of: edit (Editing), standby (Standby), active (Processing), queued (Delivering), done (Delivered)
Return type:struct
Raises:2005: Invalid operation on archived list
Raises:3001: Invalid delivery
mailer.get_delivery_stats(delivery)

Get the simple statistics of the delivery.

Parameters:delivery (integer) – ID of the delivery.
Returns:A struct of:
  • delivered_ok: Mails delivered.
  • delivered_fail: Mails bounced.
  • views: Total views.
  • views_unique: Unique views (readers).
  • view_rate: Total view rate.
  • view_rate_unique: Unique view rate (readers).
  • clicks: Total clicks.
  • clicks_unique: Unique clicks.
  • click_rate_delivered: Click rate (of delivered).
  • click_rate_views: Click rate (of views).
  • click_rate_delivered_unique: Unique click rate (of delivered).
  • click_rate_views_unique: Unique click rate (of views).
  • online_views: Total online views.
  • online_views_unique: Unique online views.
  • complaints: Total complaints.
  • complaint_rate: Total complaint rate.
  • unsubscriptions: Total unsubscriptions.
  • unsubscription_rate: Total unsubscription rate.
Return type:struct
Raises:2005: Invalid operation on archived list
Raises:3001: Invalid delivery

Note

All rates are represented as the XML-RPC double type.

mailer.get_delivery_template_content(delivery)

Get the template configuration objects for a delivery.

Parameters:delivery (integer) – ID of the delivery.
Returns:JSON encoded string of the content object.
Return type:string
Raises:2005: Invalid operation on archived list
Raises:3001: Invalid delivery
mailer.list_all_deliveries()

Get list of all deliveries.

Returns:A list of structs of:
  • id: ID if the delivery. (integer ID)
  • subject: Subject of the delivery.
  • send_time: The send time of the delivery (if available)
  • list: The list ID. (integer ID)
  • state: Delivery state. One of: edit (Editing), standby (Standby), active (Processing), queued (Delivering), done (Delivered)
Return type:array
Raises:2005: Invalid operation on archived list
mailer.list_deliveries(state, offset)

Get list of deliveries (the first 50 after offset).

Parameters:
  • state (string) – Delivery state filter. One of: edit (Editing), standby (Standby), active (Processing), queued (Delivering), done (Delivered)
  • offset (integer) – (0-indexed) Offset.
Returns:

A list of structs of:

  • id: ID if the delivery. (integer ID)
  • subject: Subject of the delivery.
  • send_time: The send time of the delivery (if available)
  • list: The list ID. (integer ID)
  • state: Delivery state. One of: edit (Editing), standby (Standby), active (Processing), queued (Delivering), done (Delivered)
Return type:

array
Raises:

2005: Invalid operation on archived list
Raises:

5003: Invalid offset
mailer.send_delivery(delivery, send_time)

Queues the delivery for delivery.

Parameters:
  • delivery (integer) – ID of the delivery.
  • send_time (string) – When should the delivery start (YYYY-MM-DD HH:MM:SS).
Returns:

True on success.
Return type:

boolean
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
Raises:

3002: Delivery not in edit state
Raises:

4008: Sender is not verified
Raises:

5001: Invalid date/time format
mailer.set_delivery_in_archive(delivery, in_archive)

Configures the visibility of the delivery in the archive.

Parameters:
  • delivery (integer) – ID of the delivery.
  • in_archive (boolean) – Should the delivery be made available in the archive
Returns:

True on success.
Return type:

boolean
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
Raises:

3006: Delivery not sent

Important

If used, it must be called after send_delivery.

mailer.set_delivery_sender(delivery, sender_email, sender_name)

Sets sender details for a delivery.

Parameters:
  • delivery (integer) – ID of the delivery.
  • sender_email (string) – E-mail address of the proposed sender
  • sender_name (string) – Name of the proposed sender
Returns:

True on success.
Return type:

boolean
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
Raises:

3002: Delivery not in edit state
Raises:

4008: Sender is not verified
Raises:

5022: Invalid sender or duplicates found

Important

If used, it must be called before send_delivery.

Important

The sender must exist in Ubivox.

mailer.set_delivery_sender_rewrite_data_field(delivery, data)

Sets sender rewrite data field for a delivery.

Parameters:
  • delivery (integer) – ID of the delivery.
  • data (string) – Data key of the data field
Returns:

True on success.
Return type:

boolean
Raises:

1005: Invalid data field key
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
Raises:

3002: Delivery not in edit state

Important

If used, it must be called before send_delivery.

mailer.set_delivery_subset_rules(delivery, subset_rules)

Sets the subset (segmentation) rules for a delivery.

Parameters:
  • delivery (integer) – ID of the delivery.
  • subset_rules (string) – JSON string of subset rules.
Returns:

True on success.
Return type:

boolean
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
Raises:

3002: Delivery not in edit state
Raises:

5008: Invalid rule set
Raises:

9995: Account type upgrade needed (contact sales)

Important

If used, it must be called before send_delivery.

Note

The JSON string containing the rules can be obtained from the Ubivox system by making a segmentation rule set and using the keyboard shortcut ctrl+shift+x.

mailer.suspend_delivery(delivery)

Suspends a delivery in the standby state and reverts to the edit state.

Parameters:delivery (integer) – ID of the delivery.
Returns:True on success.
Return type:boolean
Raises:2005: Invalid operation on archived list
Raises:3001: Invalid delivery
Raises:3003: Delivery not in standby state
mailer.test_delivery(delivery, subscriber)

Send a test delivery to a test recipient.

Parameters:
  • delivery (integer) – ID of the delivery.
  • subscriber (string) – The e-mail address of a test subscriber.
Returns:

True on success.
Return type:

boolean
Raises:

1002: The user is not subscribed
Raises:

1008: The subscriber is not a test recipient
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
Raises:

3002: Delivery not in edit state

Note

The test subscriber must exist and be configured as a test recipient on the list of the delivery. See: set_subscription_testrecipient()

mailer.update_delivery(delivery, subject, html_body, text_body, list)

Updates a delivery.

Parameters:
  • delivery (integer) – ID of the delivery.
  • subject (string) – Subject for the delivery.
  • html_body (string) – The HTML body of the delivery including logic for merging.
  • text_body (string) – The text body of the delivery including logic for merging.
  • list (integer) – The mailing list to be used. (integer ID)
Returns:

The delivery ID on success.
Return type:

integer
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
Raises:

3002: Delivery not in edit state
Raises:

3004: Problem with delivery content
Raises:

5014: Invalid subject
mailer.update_delivery_template_content(delivery, subject, template_content, list)

Updates a delivery with a new template content.

Parameters:
  • delivery (integer) – ID of the delivery.
  • subject (string) – Subject for the delivery.
  • template_content (string) – The content object encoded as JSON.
  • list (integer) – The mailing list to be used. (integer ID)
Returns:

The delivery ID on success.
Return type:

integer
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
Raises:

3002: Delivery not in edit state
Raises:

3004: Problem with delivery content
Raises:

3008: Invalid template content
Raises:

5014: Invalid subject

splittest methods

mailer.send_splittest(list, title, delivery_a, delivery_b, send_time_a, send_time_b, snapshot_a, snapshot_b, send_time_final_a, send_time_final_b, test_size, criteria_operator, criteria_variable, criteria_threshold, subset_rules)

Create a new split test using two existing deliveries..

Parameters:
  • list (integer) – The mailing list to be used. (integer ID)
  • title (string) – Internal indentification title of the split test
  • delivery_a (integer) – ID of the A delivery.
  • delivery_b (integer) – ID of the B delivery.
  • send_time_a (string) – When should the A delivery start (YYYY-MM-DD HH:MM:SS).
  • send_time_b (string) – When should the B delivery start (YYYY-MM-DD HH:MM:SS).
  • snapshot_a (string) – When should the A delivery be snapshotted (YYYY-MM-DD HH:MM:SS).
  • snapshot_b (string) – When should the B delivery be snapshotted (YYYY-MM-DD HH:MM:SS).
  • send_time_final_a (string) – When should the final delivery start, if A wins (YYYY-MM-DD HH:MM:SS).
  • send_time_final_b (string) – When should the final delivery start, if B wins (YYYY-MM-DD HH:MM:SS).
  • test_size (integer) – Percentage of the recipients to be used as splits (A+B).
  • criteria_operator (string) – Operator for the win criteria.
  • criteria_variable (string) – Variable for the win criteria.
  • criteria_threshold (integer) – Threshold (in percent) needed for B to win over A.
  • subset_rules (string) – JSON string of subset rules, leave as empty string for none.
Returns:

The new split test ID on success.
Return type:

integer
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

3001: Invalid delivery
Raises:

3002: Delivery not in edit state
Raises:

5001: Invalid date/time format
Raises:

5008: Invalid rule set
Raises:

5015: Invalid percentage
Raises:

5016: Invalid criteria variable
Raises:

5017: Invalid criteria operator
Raises:

5018: Invalid schedule
Raises:

9995: Account type upgrade needed (contact sales)

Refer to these knowledge base articles for details on split testing in Ubivox:

Supported criteria operators:

  • most
  • fewest

Supported criteria variables:

  • views: Views
  • views_unique: Views (unique)
  • online_views: Online views
  • online_views_unique: Online views (unique)
  • clicks: Clicks
  • clicks_unique: Clicks (unique)
  • bounces: Bounces
  • unsubscriptions: Unsubscriptions
  • complaints: Complaints
  • target_hits: Target hits

Schedule constraints:

  • The send time of A must be before the send time of B
  • The send time of A must be before the snapshot time of A
  • The send time of B must be before the snapshot time of B
  • The snapshot time of A and B must be before both the final send time of A and B

maillist methods

mailer.copy_maillist(maillist, new_title)

Make a copy of a list with the same list settings, draft newsletters and course stages.

Parameters:
  • maillist (integer) – The ID of the mailing list.
  • new_title (string) – The name of the new mailing list.
Returns:

ID of the new list
Return type:

integer
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
mailer.course_list_stages(maillist)

Get information about stages on a course for a given mailing list.

Parameters:maillist (integer) – The ID of the mailing list.
Returns:An ordered array of structs of:
  • id: ID of the stage. (integer ID)
  • subject: Subject of the stage.
  • next_stage_interval: The interval before the next stage (in hours)
Return type:array
Raises:2001: Invalid mailing list
Raises:2005: Invalid operation on archived list
mailer.create_maillist(title, language, delivery_sender_name, delivery_sender_email, primary_data_fields)

Create a new maillist.

Parameters:
  • title (string) – The name of the maillist.
  • language (string) – The language of the maillist.
  • delivery_sender_name (string) – Name of the sender on deliveries.
  • delivery_sender_email (string) – E-mail addresss of the sender on deliveries.
  • primary_data_fields (array) – A list of data fields primary for this maillist.
Returns:

The new maillist ID on success.
Return type:

integer
Raises:

1004: Invalid data field
Raises:

5006: Invalid language
mailer.delete_maillist(maillist)

Deletes a maillist.

Parameters:maillist (integer) – The ID of the maillist
Returns:True on success.
Return type:boolean
Raises:2001: Invalid mailing list
Raises:2005: Invalid operation on archived list
mailer.get_maillist(maillist)

Get a struct of list details.

Parameters:maillist (integer) – The ID of the maillist
Returns:A struct with:
  • title: List title
  • url: URL for the list details in Ubivox
  • stats: List statistics, a list of structs:
    • date: The date
    • new_subscriptions: New subscriptions (on this day)
    • unsubscribed: Unsubscribed (on this day)
    • removed: Removed (on this day)
    • unsubscribed_removed: Unsubscribed or removed (on this day)
    • suspended: Suspended (on this day)
    • growth: Net growth (on this day)
    • active_total: Total active subscriptions (as of this day)
    • pending_total: Total pending subscriptions (as of this day)
    • unsubscribed_total: Total unsubscribed subscriptions (as of this day)
    • removed_total: Total removed subscriptions (as of this day)
    • unsubscribed_removed_total: Total unsubscribed or removed subscriptions (as of this day)
    • suspended_total: Total suspended subscriptions (as of this day)
Return type:struct
Raises:2001: Invalid mailing list
Raises:2005: Invalid operation on archived list

Note

List statistics are cached for up to half an hour.

mailer.get_maillist_meta(maillist)

Get a struct of list meta data.

param integer maillist:
 

The ID of the maillist
returns:

A struct with:

  • signup_terms: Text which is shown above the signup form
  • allow_public_signups: Boolean showing whether public signups is allowed
` * public_archive: Boolean showing whether the list has a public archive
  • public_title: The list’s public title
  • description: The public list description
  • logo: The path to the list logo
rtype:struct
raises:2001: Invalid mailing list
raises:2005: Invalid operation on archived list
mailer.get_maillists()

Note

This method is an alias for: ubivox.list_maillists()

mailer.list_maillists()

Get a list of available mailing lists.

Returns:A list of structs:
  • id: Maillist ID
  • title: The title of the mailing list
Return type:array
mailer.maillist_archive(maillist, count)

Find the most recently archived newsletters for a given list.

Parameters:
  • maillist (integer) – The ID of the mailing list.
  • count (integer) – The amount of newsletters to return.
Returns:

An ordered (by newsletter send time in descending order) array of structs of:

  • id: ID of the newsletter. (integer ID)
  • subject: Subject of the newsletter.
  • archive_url: URL to the newsletter in the archive.
  • archive_html: HTML version of the archived newsletter.
  • send_time: When was the newsletter sent.
Return type:

array
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
mailer.maillist_archive_meta(maillist, count)

Find the most recently archived newsletters for a given list (without the HTML body).

Parameters:
  • maillist (integer) – The ID of the mailing list.
  • count (integer) – The amount of newsletters to return.
Returns:

An ordered (by newsletter send time in descending order) array of structs of:

  • id: ID of the newsletter. (integer ID)
  • subject: Subject of the newsletter.
  • archive_url: URL to the newsletter in the archive.
  • send_time: When was the newsletter sent.
Return type:

array
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
mailer.update_maillist(maillist, title, language, delivery_sender_name, delivery_sender_email, primary_data_fields)

Updates an existing maillist.

Parameters:
  • maillist (integer) – The ID of the maillist.
  • title (string) – The name of the maillist.
  • language (string) – The language of the maillist.
  • delivery_sender_name (string) – Name of the sender on deliveries.
  • delivery_sender_email (string) – E-mail addresss of the sender on deliveries.
  • primary_data_fields (array) – A list of data fields primary for this maillist.
Returns:

True on success.
Return type:

boolean
Raises:

1004: Invalid data field
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

5006: Invalid language
mailer.update_maillist_optin_optout_settings(maillist, optin_subject, optin_body, optin_success_url, optin_failure_url, optout_success_url)

Updates the opt-in/opt-out settings of an existing maillist.

Parameters:
  • maillist (integer) – The ID of the maillist.
  • optin_subject (string) – Subject of the opt-in e-mail.
  • optin_body (string) – Body of the opt-in e-mail (remember %(link)s for the opt-in link).
  • optin_success_url (string) – Success URL for opt-in.
  • optin_failure_url (string) – Failure URL for opt-in.
  • optout_success_url (string) – Success URL for opt-out.
Returns:

True on success.
Return type:

boolean
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list

email methods

mailer.send_email(recipient_email, send_time, reference, sender_email, subject, html_body, text_body)

Create a new e-mail and schedule it for delivery at send_time.

Parameters:
  • recipient_email (string) – The recipient e-mail address.
  • send_time (string) – The send time.
  • reference (string) – A preferably unique reference for this e-mail.
  • sender_email (string) – The sender e-mail address.
  • subject (string) – The subject of the e-mail.
  • html_body (string) – The HTML body of the e-mail.
  • text_body (string) – The text body of the e-mail.
Returns:

The reference of the e-mail on success.
Return type:

string
Raises:

1001: Invalid e-mail address
Raises:

5001: Invalid date/time format
Raises:

5004: Invalid reference (only a-z, A-Z, 0-9, - and _ allowed)
Raises:

5021: Invalid or empty body
Raises:

9995: Account type upgrade needed (contact sales)
Raises:

9996: Not approved for this call

Hint

Leave the reference as the empty string to have Ubivox create one for you.

mailer.send_email_from_newsletter(recipient_email, data, send_time, reference, sender_email, sender_name, subject, delivery)

Create a new e-mail and schedule it for delivery at send_time.

Parameters:
  • recipient_email (string) – The recipient e-mail address.
  • data (struct) – Extra data for the mail merging
  • send_time (string) – The send time.
  • reference (string) – A preferably unique reference for this e-mail.
  • sender_email (string) – The sender e-mail address.
  • sender_name (string) – The sender name.
  • subject (string) – The subject of the e-mail.
  • delivery (integer) – The (integer) ID of a newsletter in Ubivox
Returns:

The reference of the e-mail on success.
Return type:

string
Raises:

1001: Invalid e-mail address
Raises:

3001: Invalid delivery
Raises:

3004: Problem with delivery content
Raises:

3005: Mail merging error
Raises:

5001: Invalid date/time format
Raises:

5004: Invalid reference (only a-z, A-Z, 0-9, - and _ allowed)
Raises:

9995: Account type upgrade needed (contact sales)
Raises:

9996: Not approved for this call

Hint

Leave the reference as the empty string to have Ubivox create one for you.

If the recipient is known to Ubivox, we will use their data as a base and overwrite the final mail merging context with any data you supply in data.

If any of sender_email, sender_name or subject is left blank, we will use the defaults from the list associated with the newsletter.

mailer.send_email_rfc2822(recipient_email, send_time, reference, message)

Create a new e-mail and schedule it for delivery at send_time.

Parameters:
  • recipient_email (string) – The recipient e-mail address.
  • send_time (string) – The send time.
  • reference (string) – A preferably unique reference for this e-mail.
  • message (string) – The raw (RFC2822) message.
Returns:

The reference of the e-mail on success.
Return type:

string
Raises:

1001: Invalid e-mail address
Raises:

5001: Invalid date/time format
Raises:

5004: Invalid reference (only a-z, A-Z, 0-9, - and _ allowed)
Raises:

5019: Invalid encoding
Raises:

9995: Account type upgrade needed (contact sales)
Raises:

9996: Not approved for this call

Hint

Leave the reference as the empty string to have Ubivox create one for you.

mailer.send_email_with_names(recipient_email, recipient_name, send_time, reference, sender_email, sender_name, subject, html_body, text_body)

Create a new e-mail and schedule it for delivery at send_time.

Parameters:
  • recipient_email (string) – The recipient e-mail address.
  • recipient_name (string) – The recipient name.
  • send_time (string) – The send time.
  • reference (string) – A preferably unique reference for this e-mail.
  • sender_email (string) – The sender e-mail address.
  • sender_name (string) – The sender name.
  • subject (string) – The subject of the e-mail.
  • html_body (string) – The HTML body of the e-mail.
  • text_body (string) – The text body of the e-mail.
Returns:

The reference of the e-mail on success.
Return type:

string
Raises:

1001: Invalid e-mail address
Raises:

5001: Invalid date/time format
Raises:

5004: Invalid reference (only a-z, A-Z, 0-9, - and _ allowed)
Raises:

5021: Invalid or empty body
Raises:

9995: Account type upgrade needed (contact sales)
Raises:

9996: Not approved for this call

Hint

Leave the reference as the empty string to have Ubivox create one for you.

media methods

mailer.media_delete(filename)

Deletes a media file on the server.

Parameters:filename (string) – Relative filename of the media file (including directories).
Returns:True on success.
Return type:boolean
Raises:5007: Invalid filename
mailer.media_upload(filename, data)

Writes a media file on the server. Will overwrite existing files.

Parameters:
  • filename (string) – Relative filename of the media file (including directories).
  • data (base64) – The data of the media file.
Returns:

True on success.
Return type:

boolean
Raises:

5007: Invalid filename

data methods

mailer.create_data_field(key, title, data_type, access, required, sort, archive_value)

Create a data field.

Parameters:
  • key (string) – The key of the data field.
  • title (string) – The title of the data field.
  • data_type (string) – The data type. One of the following: text (Text field: Single line), textarea (Text field: Multi line), checkbox (Checkbox: Single), select (Select: Single), select_multiple (Select: Multiple), select_radio (Select: Radio buttons (single)), select_checkbox (Select: Check boxes (multiple))
  • access (string) – Access level: public (Shown to users) or private (Only visible to administrators).
  • required (boolean) – Is this field required.
  • sort (integer) – An integer indicating the sort order.
  • archive_value (string) – Default value for archive displays
Returns:

True on success.
Return type:

boolean
Raises:

1005: Invalid data field key
Raises:

1006: Invalid data field type
Raises:

1007: Invalid data field access
mailer.get_data_keys()

Note

This method is an alias for: ubivox.list_data_fields()

mailer.hide_data_field(key)

Hide the data field.

Parameters:key (string) – The key of the data field
Returns:True on success.
Return type:boolean
Raises:1004: Invalid data field
mailer.list_data_fields()

Retrieve the available data fields for user data.

Returns:A list of keys.
Return type:array
mailer.list_data_fields_details()

Retrieve the available data fields for user data with data field details.

Returns:A list of structs of:
  • id - A unique integer ID for the data field
  • key - The key of the data field
  • title - The title of the data field
  • datatype - The type of the data field (currenly only text (single line text field))
  • access - Who can see the data field (public or private)
  • required - Is the data field required (boolean)
  • archive_value - The archive value of the data field
  • choices - Predefined choices for the data field
  • sort - Sort order (priority)
Return type:struct
mailer.update_data_field(key, title, data_type, access, required, sort, archive_value)

Update a data field.

Parameters:
  • key (string) – The key of the data field (cannot be changed).
  • title (string) – The new title of the data field.
  • data_type (string) – The data type. One of the following: text (Text field: Single line), textarea (Text field: Multi line), checkbox (Checkbox: Single), select (Select: Single), select_multiple (Select: Multiple), select_radio (Select: Radio buttons (single)), select_checkbox (Select: Check boxes (multiple))
  • access (string) – Access level: public (Shown to users) or private (Only visible to administrators).
  • required (boolean) – Is this field required.
  • sort (integer) – An integer indicating the sort order.
  • archive_value (string) – Default value for archive displays
Returns:

True on success.
Return type:

boolean
Raises:

1004: Invalid data field
Raises:

1006: Invalid data field type
Raises:

1007: Invalid data field access
mailer.update_data_field_options(key, options)

Update a data field.

Parameters:
  • key (string) – The key of the data field to be updated
  • options (array) –

    A list of structs with:

    • order - Sort order (integer)
    • key - The key of the option (string, what will be saved)
    • value - The value of t he option (string, what will be displayed)
Returns:

True on success.
Return type:

boolean
Raises:

1004: Invalid data field

Hint

Leave the options parameter as an empty list, to remove all options.

imports methods

mailer.import_history()

Retrieve a list of past imports. Refer to the web interface for details.

Returns:A list of structs:
  • filename - Filename of the import
  • uploaded - Date and time for the upload
  • imported - Date and time when finished
  • maillist - Maillist ID import to
Return type:array
mailer.import_new(filename, data, maillist, consent_details, update_data, ignore_empty_data, activate_suspended, unsubscribe_other)

Create new import job and starts the processing immediately.

Parameters:
  • filename (string) – The filename of the import.
  • data (base64) – The data of the import file.
  • maillist (integer) – The ID of the maillist the subscriptions should be imported to.
  • consent_details (string) – The cirsumstances under which consent was given for these addresses. Will be public to the subscriber.
  • update_data (boolean) – Update data on existing subscriptions?
  • ignore_empty_data (boolean) – Ignore empty values when updating data fields?
  • activate_suspended (boolean) – Activate suspended subscriptions?
  • unsubscribe_other (boolean) – Unsubscribe subscribers not in the import file?
Returns:

True on success.
Return type:

boolean
Raises:

1005: Invalid data field key
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

4002: Too many invalid addresses in import file
Raises:

4003: Another import already exists with this filename
Raises:

4004: Invalid import filename

Warning

A common pitfall of this method is that the data parameter must be of the base64 XML-RPC data type, and not just a base64 encoded string. Refer to your XML-RPC library documentation for implementation notes.

mailer.import_queue()

Retrieve a list of currently processing and queued imports. Refer to the web interface for details.

Returns:A list of structs:
  • filename - Filename of the import
  • uploaded - Date and time for the upload
  • started - Date and time when processing started (0000-00-00T00:00:00 if not started yet)
  • maillist - Maillist ID import to
  • progress - The progress expressed as an integer percentage
Return type:array

exports methods

mailer.export_download(export)

Downloads a finished export.

Parameters:export (integer) – The ID of the export to download.
Returns:A struct containing:
  • filename - The filename of the export
  • format - The format of the export (xls or csv)
  • contents - The contents of the export
Return type:struct
Raises:4006: Invalid export
Raises:4007: Export is not done processing yet

Note

The contents of the file is sent as a base64 XML-RPC data type. Refer to your XML-RPC library documentation for implementation notes.

mailer.export_history()

Retrieve a list of past exports. Refer to the web interface for details.

Returns:A list of structs:
  • id - ID of the export
  • maillist - Maillist ID
  • title - Title of the export
  • start_time - When was the export started
  • format - csv or xls
  • state - ordered, processing or done
Return type:array
mailer.export_order(maillist, title, start_time, format, data, export_active, export_suspended, export_unsubscribed, export_removed)

Order a new export. Refer to the web interface for details.

Parameters:
  • maillist (integer) – The ID of the maillist containing subscriptions for this export.
  • title (string) – The title of the export (for identification).
  • start_time (string) – When can we start processing the export (YYYY-MM-DD HH:MM:SS).
  • format (string) – Either csv or xls.
  • data (array) – An array of data keys to include in the export.
  • export_active (boolean) – Include active subscriptions in export.
  • export_suspended (boolean) – Include suspended subscriptions in export.
  • export_unsubscribed (boolean) – Include unsubscribed subscription in export.
  • export_removed (boolean) – Include removed subscriptions in export.
Returns:

New export ID on success
Return type:

integer
Raises:

1004: Invalid data field
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

5001: Invalid date/time format

target methods

mailer.create_target(title, description)

Create a new target.

Parameters:
  • title (string) – The name of the target.
  • description (string) – The description of the target.
Returns:

The new target ID on success.
Return type:

integer
mailer.list_targets()

Get a list of available targets.

Returns:A list of structs:
  • id: Target ID
  • title: The title of the target
  • description: The description of the target
Return type:array
mailer.target_statistics(target)

Fetches statistics for an existing target.

Parameters:target (integer) – The ID of the target.
Returns:A struct of:
  • title: Title of the target.
  • description: Description of the target.
  • hits: Hits to this target.
  • time: Average time in seconds to reach target.
Return type:struct
Raises:5010: Invalid target
mailer.update_target(target, title, description)

Updates an existing target.

Parameters:
  • target (integer) – The ID of the target.
  • title (string) – The name of the target.
  • description (string) – The description of the target.
Returns:

True on success.
Return type:

bool
Raises:

5010: Invalid target

webhook methods

mailer.create_webhook(hook, url, throttle_per_minute, max_retries)

Create a new webhook.

Parameters:
  • hook (string) – The hook to attach to, see Supported hooks for webhooks.
  • url (string) – The URL to call.
  • throttle_per_minute (integer) – How many calls will we attempt per minute.
  • max_retries (integer) – How many times will we retry a call.
Returns:

The (integer) ID of the new webhook on success.
Return type:

int
Raises:

5012: Invalid hook
mailer.delete_webhook(id)

Delete an existing webhook.

Parameters:id (integer) – The ID of the webhook.
Returns:True on success.
Return type:boolean
Raises:5011: Invalid webhook
mailer.delete_webhook_by_url(url)

Delete an existing webhook.

Parameters:url (string) – The URL of the webhook(s).
Returns:True on success.
Return type:boolean
Raises:5011: Invalid webhook
mailer.list_webhooks()

Retrieve the available, configured webhooks.

Returns:A list of structs of:
  • id - A unique integer ID for the webhook
  • hook - The configured hook
  • url - The configured URL to call
  • throttle_per_minute - How many calls will we attempt per minute
  • max_retries - How many times will we retry a call
Return type:array
mailer.update_webhook(id, hook, url, throttle_per_minute, max_retries)

Update an existing webhook.

Parameters:
  • id (integer) – The ID of the webhook.
  • hook (string) – The hook to attach to, Supported hooks for webhooks.
  • url (string) – The URL to call.
  • throttle_per_minute (integer) – How many calls will we attempt per minute.
  • max_retries (integer) – How many times will we retry a call.
Returns:

True on success.
Return type:

boolean
Raises:

5011: Invalid webhook
Raises:

5012: Invalid hook

account methods

mailer.account_flag(flag)

Check the status of a given account flag.

Parameters:flag (string) – The name of the flag. See below.
Returns:Contents of the flag or the empty string for unknown flags.
Return type:string

Currently supported flags:

  • has_verified_sender

    yes or no depending on whether the account has Verified Sender enabled.

  • verified_sender_cert_url

    The URL for the verified sender certificate or the empty string if Verified Sender is not enabled.

mailer.account_invoice_details(invoice_number)

List all invoices on account

Returns:Struct with:
  • number: Number (string)
  • date: Date (string)
  • currency: Currency (string, ISO 4217)
  • paid: Paid (boolean)
  • paid_text: Text describing the payment (string)
  • paid_amount: How much was paid (double)
  • paid_fee: How much was paid in fees (double)
  • paid_date: On what day was the payment fulfilled (string)
  • invoice_lines: Array invoice lines as structs with:
    • product_number: Product number (string)
    • quantity: Quantity (integer)
    • unit: Unit (string)
    • unit_net_amount: Net amount per unit (double)
    • total_net_amount: Total net amount for line (double)
    • taxes: Any value added taxes related to this line as array of structs with:
      • name: Name of the tax (string)
      • percentage: Tax percentage (double)
      • amount: Amount to be paid in tax (double)
  • payments: Array of payment receipts as structs with:
    • opened: Payment opened (string)
    • confirmed: Payment confirmed (string)
    • fee: The payment fee for this payment (double)
    • amount: Amount paid (double)
    • reference: Reference (string)
  • net_amount: Net amount (string)
  • vat_amount: VATs amount (string)
  • gross_amount: Gross amount (string)
Return type:struct
Raises:5020: Invalid invoice
mailer.account_invoice_list()

List all invoices on account

Returns:Array of structs with:
  • number: Number (string)
  • date: Date (string)
  • due_date: Payment due date (string)
  • currency: Currency (string, ISO 4217)
  • gross_amount: Gross amount (string)
  • paid: Paid (boolean)
Return type:array
mailer.account_invoice_pdf(invoice_number)

Fetch an invoice as PDF

Parameters:invoice_number (integer) – Invoice number
Returns:The invoice as PDF (as XML-RPC base64 encoded binary).
Return type:base64
Raises:5020: Invalid invoice
mailer.account_status()

Get an account status struct suitable for producing an account dashboard.

Returns:struct:
  • lists: Your lists (limited to 25)
    • title: List title
    • url: URL for the list details in Ubivox
    • stats: List statistics, a list of structs:
      • date: The date
      • new_subscriptions: New subscriptions (on this day)
      • unsubscribed: Unsubscribed (on this day)
      • removed: Removed (on this day)
      • unsubscribed_removed: Unsubscribed or removed (on this day)
      • suspended: Suspended (on this day)
      • growth: Net growth (on this day)
      • active_total: Total active subscriptions (as of this day)
      • pending_total: Total pending subscriptions (as of this day)
      • unsubscribed_total: Total unsubscribed subscriptions (as of this day)
      • removed_total: Total removed subscriptions (as of this day)
      • unsubscribed_removed_total: Total unsubscribed or removed subscriptions (as of this day)
      • suspended_total: Total suspended subscriptions (as of this day)
  • drafts: Your newsletter drafts (latest 25 only)
    • subject: Subject of the newsletter
    • edit_time: Last edited time
    • url: URL for the newsletter details in Ubivox
    • list_title: The title of the list of the newsletter
    • list_url: URL the the list details of the list of the newsletter
  • published: Your published, sent newsletters (latest 25 only)
    • subject: Subject of the newsletter
    • send_time: Last edited time
    • url: URL for the newsletter details in Ubivox
    • list_title: The title of the list of the newsletter
    • list_url: URL the the list details of the list of the newsletter
    • recipients: Total number of recipients
    • delivered: Total number of successful deliveries
    • views: Total number of views (opens) on this newsletter
    • clicks: Total number of clicks on this newsletter
Return type:struct

Note

List statistics are cached for up to half an hour.

sync methods

mailer.synchronize(new_subscriptions, maillist, optin, unsubscriptions_from)

Working with your local CRM or database system as master, synchronize new subscriptions to Ubivox while getting information about unsubscriptions from Ubivox as well.

Parameters:
  • new_subscriptions (array) –

    An array (max length 500) of structs with:

    • email - The e-mail address of the subscriber.
    • time - The time of the new subscription (optional, see note)
    • data - A struct of data fields to be updated. See Subscriber data.
    • consent_details - A text describing the circumstances under which consent was given.
  • maillist (integer) – The list IDs for the subscribers to be subscribed to. Also has effect on the returned unsubscriptions.
  • optin (boolean) – Should we send opt-in e-mails for this synchronization call.
  • unsubscriptions_from (string) – Return unsubscriptions from this point in time. (Leave as empty string to disable)
Returns:

A struct with:

  • status - An array of structs with details regarding the new subscriptions:

    • email - The e-mail address of the subscriber.
    • subscriber_id - The subscriber id, may be NULL if the e-mail address is considered invalid.
    • subscription_id - The resulting subscription id, may be NULL if we ignored the request due to block lists or existing unsubscriptions.
    • message - A human readable message detailing what we did with this subscriber.

  • unsubscriptions - An array of structs with details regarding unsubscriptions that occurred since the specified time:

    • email - The e-mail address of the subscriber.
    • subscriber_id - The subscriber id.
    • subscription_id - The ID of the unsubscription.
    • time - Time stamp for the unsubscription.
Return type:

struct
Raises:

1011: New subscriptions blocked for your account
Raises:

2001: Invalid mailing list
Raises:

2005: Invalid operation on archived list
Raises:

5001: Invalid date/time format

Note

If you do not include a subscription time in the new_subscriptions structs, the presence of an earlier unsubscription will cause us to ignore the new subscription request. If you include it, and the new subscription time is later than the unsubscription time we have on file, the new subscription will be allowed.

This method is meant to be run using cron or a similar mechanism, synchronizing your new subscription from your system to Ubivox and also fetching unsubscriptions from Ubivox to your system. We recommend running it in daily or hourly schedules, depending on your load and needs.

If you need one-time batch imports of large subscriber sets, we recommend you use the import API, see imports methods.

This method is idempotent in the sense that the system will ignore requests to subscribe already subscribed adresses and the returned unsubscriptions doesn’t have any side effects on the system.

Status messages

The returned status messages can be:

  • Invalid e-mail address.

    The e-mail address didn’t validate or was present on a blacklist.

  • Subscriber on stop list.

    The subscriber is on your stop list and cannot be added without using opt-in.

  • Suspended subscriber.

    The subscriber is suspended on one or more of your lists.

  • Already subscribed (state).

    The subscriber is already subscribed to your list in the state state.

  • Subscription created.

    A new subscription was successfully created for this subscriber.

Warning

It is the responsibility of the caller to archive the status messages in order to debug why a given subscriber was blocked.

ecommerce methods

mailer.ecommerce_tracking_cancel_order(customer_ref, order_ref)

Cancels an order previously registered.

Parameters:
  • customer_ref (string) – Your customer reference
  • order_ref (string) – Your order reference
Returns:

True on success, False if the order wasn’t found
Return type:

boolean
Raises:

9995: Account type upgrade needed (contact sales)

Note

Refer to the Ecommerce Tracking documentation for details.

mailer.ecommerce_tracking_html(customer_ref, order_ref)

Register new sale for a contact.

Parameters:
  • customer_ref (string) – Your customer reference
  • order_ref (string) – Your order reference
Returns:

A HTML snippet for pinging your ecommerce tracking data from the client side potentially allowing to associate the sale with a click/newsletter
Return type:

string
Raises:

9995: Account type upgrade needed (contact sales)

Note

Refer to the Ecommerce Tracking documentation for details.

mailer.ecommerce_tracking_new_order(params, email_address, maillist)

Register new sale for a contact.

Parameters:
  • params (struct) – Ecommerce tracking order parameters.
  • email_address (string) – E-mail address of the contact
  • maillist (integer) – To associate the sale with a specific list, pass the maillist ID here. Leave as 0 for no maillist association.
Returns:

“OK” for success. In case of problems parsing your ecommerce tracking parameters, an error message will be returned.
Return type:

string
Raises:

2001: Invalid mailing list
Raises:

9995: Account type upgrade needed (contact sales)

Note

Refer to the Ecommerce Tracking documentation for details on the order parameters.

misc methods

mailer.ping()

Note

This method is an alias for: ubivox.server_time()

mailer.server_time()

Returns the current server time.

Returns:The server time
Return type:string
mailer.time_zone()

Get information on the current time zone of the account.

Returns:The time zone name.
Return type:string
mailer.time_zones()

Get information on the supported time zones.

Returns:An array of supported time zones
Return type:array