Definitions

Date/time formats and time zone

All date and time values can either be sent as strings or as the XML-RPC dateTime.iso8601 type. If you choose to send it as strings, they must be sent with the following format:

Date:
YYYY-MM-DD (E.g.: 2010-05-31)
Date with time:
YYYY-MM-DD HH:MM:SS (E.g.: 2010-05-31 18:42:53)
Time:
HH:MM:SS (E.g.: 18:42:53)

If you choose to send you dates and times as the dateTime.iso8601 type, you must conform to the XML-RPC specification.

All dateTime.iso8601 timestamps are interpreted according to the account time zone.

There is also a special case to indicate the current time: Send the string now.

Time zone support

The timestamps you send to the API will be interpreted according to the time zone your account has been configured with. This can be configured from the Ubivox interface: Account and then Contact details.

Note

The current local time for the account (in the time zone, as configured on the contact details) can be looked up by calling mailer.server_time().

Note

An array of the supported time zones can be fetched from the API using mailer.time_zones().

Error codes

All error reporting is done through XML-RPC fault messages. The following error conditions can happen:

Error code Error message
1001 Invalid e-mail address
1002 The user is not subscribed
1003 The user is already subscribed
1004 Invalid data field
1005 Invalid data field key
1006 Invalid data field type
1007 Invalid data field access
1008 The subscriber is not a test recipient
1009 Invalid subscriber
1010 Missing consent
1011 New subscriptions blocked for your account
2001 Invalid mailing list
2002 The course has already ended (no stage to advance to)
2003 Invalid stage.
2004 Opt-in not configured (on one or more lists).
2005 Invalid operation on archived list
3001 Invalid delivery
3002 Delivery not in edit state
3003 Delivery not in standby state
3004 Problem with delivery content
3005 Mail merging error
3006 Delivery not sent
3007 Invalid template
3008 Invalid template content
4001 Invalid import
4002 Too many invalid addresses in import file
4003 Another import already exists with this filename
4004 Invalid import filename
4005 Format error in import file
4006 Invalid export
4007 Export is not done processing yet
5001 Invalid date/time format
5002 Invalid date format
5003 Invalid offset
5004 Invalid reference (only a-z, A-Z, 0-9, - and _ allowed)
5005 Invalid time zone
5006 Invalid language
5007 Invalid filename
5008 Invalid rule set
5009 Invalid timezone
5010 Invalid target
5011 Invalid webhook
5012 Invalid hook
5013 Invalid user
5014 Invalid subject
5015 Invalid percentage
5016 Invalid criteria variable
5017 Invalid criteria operator
5018 Invalid schedule
5019 Invalid encoding
5020 Invalid invoice
5021 Invalid or empty body
5022 Invalid sender or duplicates found
6001 Wrong number of parameters given
6002 No such method
7001 Invalid client
7002 FTP username taken
7003 Hostname taken
7004 Username taken
7005 Invalid user
7006 Account name taken
7007 Invalid account type
7008 Invalid account name
7009 Missing address field for customer
7010 Invalid method
7011 Cannot approve a customer that’s not active
9992 Invalid multicall call struct
9993 Recursive multicall not allowed
9994 Unauthorized
9995 Account type upgrade needed (contact sales)
9996 Not approved for this call
9997 Too many calls (throttling)
9998 XML error (maybe not wellformed)
9999 Unknown error

In each method, error conditions that can occur is listed.

Subscriber data

All API methods that work with subscriber data do so by utilizing the XML-RPC struct type (see Protocols). The struct is a mapping from the data key to the data value for this particular subscriber.

Data fields with predefined options

When dealing with data fields with predefined options, you need to supply the keys of your options in a comma separated string as the value of the data field.

Supported hooks for webhooks

We currently support the following hooks/events for webhooks:

  • subscription
  • unsubscription
  • remove_subscription
  • suspend_subscription
  • activate_subscription
  • login
  • junk_delivery
  • junk_email
  • bounced_email

For explanations, please refer to the Ubivox webhook interface located inside the Ubivox system from Account then Webhooks.

Stoplist causes

These are the different causes that may get a subscriber on the stoplist depending on your account configuration:

  • junkreport: We received an automatic (or manual) junk report for the subscriber.
  • admin: Administrative request.
  • unknown: Unknown cause.
  • unsubscription: Unsubscription (only if enabled by contacting Ubivox)
  • bounce: Bounce (only if enabled by contacting Ubivox)