Introduction

The Taguchi API supports all of the functionality provided by the admin interface, including:

Creating and updating subscriber profiles, including custom fields and behavioural history;
Adding new subscriber lists, and managing subscription options for individual subscribers;
Creating and updating campaigns, including adding activities, editing activity content, and setting activity targets;
Sending (or scheduling) broadcasts, and setting triggered email conditions;
Sending/scheduling SMS messages;
Logging custom events on a per-subscriber basis, for reporting or triggering purposes;
Extracting lists of subscribers who match particular conditions or who have exhibited certain behaviour in the past (e.g. clicking on a specific link or opening an email).

All Taguchi APIs accept data in JSON and XML format, and can output data in either of those formats as well.

Authentication

The API server must be accessed via HTTPS, using a valid user's credentials (we recommend a new user be created for this purpose, with appropriate credentials). Your credentials carry many privileges, so be sure to keep them secret! Do not share your credentials in publicly accessible areas such GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

The base URL structure should be as follows:

https://<client-name>.taguchimail.com/admin/api/<organization-id>/

The <client-name> used in requests is the same as the client name used to log in to the Taguchi backend; this is typically edm2.taguchimail.com, but can vary if a custom domain has been configured for the server.

The <organization-id> used in requests is the same as the organization ID in Taguchi. If you have multiple organizations in your Taguchi instance, the ID can be found in the organization view when you login to V4, in V5 it is displayed in the organization view tile (in the lower left corner).

If in doubt, contact Taguchi Support.

Username/Password Auth

To authenticate using a Taguchi V4 username and password, simply append the auth to the query string of the URL, separating the username and password with a vertical bar:

https://<client-name>.taguchimail.com/admin/api/<organization-id>/?auth=sample@email.com|mySuperStr0n9P@ssW0rd

Token Auth

To authenticate using a Taguchi supplied authentication token, simply append the auth to the query string of the URL:

https://<client-name>.taguchimail.com/admin/api/<organization-id>/?auth=c73d08de890479518ed60cf670d17faa26a4a71f995c1dcc978165399401a6c4

Error Handling

Taguchi uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was missed), and codes in the 5xx range indicate an error with Taguchi's servers (these are rare).

Response Code	Status
200 - OK	Everything working as expected.
204 - No Content	No content found/returned.
400 - Bad Request	The request was not accepted, often due to missing a required parameter, the JSON/XML is not correctly serialized or there is a resource conflict in the database.
403 - Forbidden	No valid authentication or token provided.
404 - Not Found	The requested resource doesn't exist.
405 - Method Not Allowed	The resource type is not supported by the request.
406 - Not Acceptable	The requested output format is not supported.
500, 502, 503, 504 Server Errors	Something went wrong on Taguchi's end. (These are rare.)

The username and password are submitted along with the URL using the "auth" query-string parameter; the values should be correctly escaped and separated by a | character:

https://edm2.taguchimail.com/admin/api/1/subscriber/102?auth=user@example.com|password

Format Settings

The format of request and response content is determined by the Content-Type and Accept headers respectively, in accordance with RFC 2068.

Supported formats are:

application/json: Indicates JSON-formatted data as described in RFC 4627.
application/xml: Indicates XML-formatted data in the XML formats described in the API documentation for the appropriate resource type.

If the Content-Type and Accept headers cannot be set, simply include the appropriate values in the _accept and _content_type query-string parameters:

https://edm2.taguchimail.com/admin/api/1/subscriber/102?auth=user@example.com|password&_accept=application/json&_content_type=application/json

Queries

API resources capable of returning more than one object support a consistent query interface providing control over what objects are returned, and how many of them to include:

sort

One of the resource's keys, determining how the records in the result set should be sorted (defaults to the order in which records were created, from oldest to youngest).
order

Either asc or desc, determines whether records are sorted in ascending or descending order (defaults to asc).
limit

positive non-zero integer indicating the maximum number of objects to return (defaults to 1).
offset

Either 0 or a positive integer indicating the starting position of the object range to return, within the query result set (defaults to 0, meaning the query will return the first object in the result set).
query

May appear multiple times, each appearance defining a predicate to use in the resource query. The syntax is query=<field>-<operator>-<value>, where <field> is the name of the field in the objects to be returned, <value> is the string or numeric value with which <field> should be compared, and <operator> is one of the following:
Show Operators
- eq
  
  Mapped to SQL =, tests for equality between <field> and <value> (case-sensitive).
- neq
  
  Mapped to SQL !=, tests for inequality between <field> and <value> (case-sensitive).
- lt
  
  Mapped to SQL <, tests if <field> is less than <value>.
- gt
  
  Mapped to SQL >, tests if <field> is greater than <value>.
- lte
  
  Mapped to SQL <=, tests if <field> is less than or equal to <value>.
- gte
  
  Mapped to SQL >=, tests if <field> is greater than <value>.
- re
  
  Mapped to PostgreSQL ~, interprets <value> as a POSIX regular expression and tests if <field> matches it (case-sensitive).
- rei
  
  Mapped to PostgreSQL ~*, performs a case-insensitive regular expression match.
- like
  
  Mapped to SQL LIKE (case-sensitive).
- is
  
  Mapped to SQL IS (should be used to test for NULL values in the database, as <field>-eq-null will always be false).
- nt
  
  Mapped to SQL IS NOT (should be used to test for not-NULL values).

Activity Resource

Activities contain the content and metadata for emails, SMS messages, and web pages; their main purpose is to be generated and sent/displayed to individual subscribers.

Activity content is stored in a series of revisions, which provide version control functionality. Individual revisions can be approved, which enables them to be sent/displayed in response to 'live' subscriber events.

Aside from its role in the administrative interface, the activity API should be used by third-party systems to create and manage emails (e.g. in response to changes in a CMS), and send those emails to subscribers (e.g. in response to defined events or a preset send schedule).

Note that the ability to approve or reject activity revisions (or create them in the approved state) requires the API user to have appropriate privileges ('Approve Activity' and 'Reject Activity' respectively). Simply having 'Create Activity' or 'Update Activity' privileges is not enough. These privileges will normally be assigned as part of a users's membership in a User Class; contact Taguchi Support for further information.

The URI of an activity record request is similar to:

https://edm2.taguchimail.com/admin/api/<organization-id>/activity/<activity-id>

Where <organization-id> is the numeric ID of the organization to which the activity belongs (this will be allocated when an organization is created), and <activity-id> is the numeric ID of the activity record to retrieve.

An activity query URI looks like:

https://edm2.taguchimail.com/admin/api/<organization-id>/activity/?query=<query>

Where <query> is structured as described under Queries in the Introduction section.

Activity requests also support a revisions query-string parameter, which determines which of an activity's saved revisions are included in the response. The following values are supported:

deployed: Returns only the latest deployed revision;
approved: Returns only the latest approved revision;
latest: Returns only the latest revision, regardless of approval status;
history: Returns the entire revision history.

If the revisions query-string parameter is not set, no revisions are returned.

Operations

Activity resources support the following operations, specified either via the HTTP method (GET, PUT, POST, DELETE) or via the _method query-string parameter if the HTTP method cannot be changed:

GET

Retrieves an individual record (if the activity ID is present in the URI), or a list of records (using the query options described under Queries in the Introduction section).
PUT

Updates an individual record; requires the activity ID be present in the URI.
POST

Creates a new activity record; requires that no activity ID be present in the URI.
DELETE

Removes an activity record; requires that an activity ID be present in the URI.
PROOF

Sends a proof for an activity record; should be implemented as HTTP POST with _method=PROOF. Accepts the following fields via a JSON object in the request body:
Show Fields
- list_id
  
  List ID of the proof list to which the proof messages will be sent.
- subscriber_id
  
  Subscriber ID of the proof list to which the messages will be sent (overrides list_id if present).
- revision_id
  
  Send a proof of a specific revision, rather than the latest.
- protocol
  
  Either 'smtp' or 'sms', determines how the message should be delivered to the recipients.
- server
  
  If custom servers have been configured, this may be used to set the outbound SMTP or SMS gateway.
- format
  
  If protocol is 'smtp', this should be 'mime'; if protocol is 'sms', it should be 'plain'.
- tag
  
  Tag to display at the start of the subject line.
- message
  
  Custom message which will be included in the proof header.
APPROVAL

Sends an approval request for an activity record; should be implemented as HTTP POST with _method=APPROVAL. Accepts the following fields via a JSON object in the request body:
Show Fields
- list_id
  
  List ID of the approval list to which the approval requests will be sent.
- revision_id
  
  Request approval for a specific revision, rather than the latest.
- protocol
  
  Either 'smtp' or 'sms', determines how the message should be delivered to the recipients.
- server
  
  If custom servers have been configured, this may be used to set the outbound SMTP or SMS gateway.
- format
  
  If protocol is 'smtp', this should be 'mime'; if protocol is 'sms', it should be 'plain'.
- tag
  
  Tag to display at the start of the subject line.
- message
  
  Custom message which will be included in the approval request header.
COMMENT

Saves a comment to be displayed to editors of the activity record; should be implemented as HTTP POST with _method=COMMENT. Accepts the following fields via a JSON object in the request body:
Show Fields
- message
  
  Comment message.
APPROVE

Registers approval for the activity, enabling the current revision to be sent. Should be implemented as HTTP POST with _method=APPROVE. Accepts the following fields via a JSON object in the request body:
Show Fields
- message
  
  Comment message.
QUEUE

Queues activity for delivery at its scheduled date (the date field), to its specified distribution targets (target-lists and target-views fields). Should be implemented as HTTP POST with _method=QUEUE.
TRIGGER

Triggers activity, causing it to be delivered to a specified list of subscribers. Should be implemented as HTTP POST with _method=TRIGGER. Accepts the following fields via a JSON object in the request body:
Show Fields
- date
  
  Date and time (UTC) upon which the message should be sent to the designated subscribers (defaults to current date and time if not present).
- conditions
  
  Either an array of subscriber IDs to whom the message should be delivered to, or a valid target expression.
- test
  
  If 1, this is treated as a test send.
- protocol
  
  Either 'smtp' or 'sms', determines how the message should be delivered to the recipients.
- server
  
  If custom servers have been configured, this may be used to set the outbound SMTP or SMS gateway.
- format
  
  If protocol is 'smtp', this should be 'mime'; if protocol is 'sms', it should be 'plain'.
- request_content
  
  JSON/XML content for message customization. May be repeated if the subscriber_id parameter is repeated; if both parameters are repeated, the nth value of request_content will be assumed to correspond to the nth subscriber_id. The request_content document is available to the activity template's stylesheet, in addition to the revision's content.

Common Fields

id

Unique integer value used to identify the activity record within TaguchiMail. IDs are consistent for the life of an activity record, and cannot be changed or assigned.
ref

User-definable unique text field intended to store external primary keys. This value can be updated at any time.
name

The name used to identify the activity in the Taguchi UI.
type

Determines available templates and distribution mechanisms along with the UI used to edit the activity; this corresponds to the 'type' field in template records.
subtype

Determines 'suggested' vs 'other' templates in the activity UI; this corresponds to the 'subtype' field in template records.
status

Tracks the activity state, controlling display in the UI and available actions. If set to 'deleted', the activity will not appear in the UI, and will not be returned in response to API requests.
target-lists

JSON-serialized list of subscriber list IDs to which the activity should be distributed. The distribution list is the set union of the target lists.
target-views

JSON-serialized list of view constraints to which the activity distribution should be constrained. The final distribution list is the intersection of the unions of target lists and target views.
approval-status

Contains the approval token for the activity's current approved revision. Controls whether or not the activity is available for broadcast within the UI.
date

Scheduled date of the activity, which controls the time at which the activity is queued (UTC). Set to the current date and time (UTC) when the activity is actually broadcast.
throttle

Activity throttle rate in messages per second.
data

Arbitrary, user-definable activity data.
organization

Links the activity to the organization that owns it.
campaign

Links the activity to its parent campaign.
template

Links the activity to its selected template.

Revisions

Activity content is stored as a series of revisions, each of which has a timestamp and approval status. By default, revision content is not returned in activity responses, however the revisions to return can be controlled using the revisions query-string parameter (set to one of history, approved, or latest as described above).

Revisions contain the following fields:

id

ID of the revision record in the database.
content

Contains revision XML content. This is typically set up in the Taguchi UI, and normally includes an XML document structure based on RSS. However, if UI access is not required, this content can have an arbitrary (valid) structure; the only requirement is that the transform associated with the template convert this content into a valid intermediate MIME document.
template-revision

Links the activity revision to a specified template revision.
combinations

Lists the combinations of content defined by the revision. This list is generated when the revision is created, by creating one combination record for every combination of 'level' defined within the transformed revision content.

For example, if the template contains <fragment> elements with groups A, B and C and IDs A1, A2, B1, B2, C1, C2, C3, the following 12 combinations will be created: A1|B1|C1, A1|B1|C2, A1|B1|C3, A1|B2|C1, A1|B2|C2, A1|B2|C3, A2|B1|C1, A2|B1|C2, A2|B1|C3, A2|B2|C1, A2|B2|C2, A2|B2|C3.

Combinations are used by the various template transforms to determine visibility of sections within the revision's content; in XSLT-based templates these correspond to <fragment> elements.

Combinations contain the following fields: id: ID of the combination record in the database. fragment-ids: Revision fragment IDs visible in the combination.
approval-status

If 'deployed', this revision is publicly available, otherwise only test events may use this revision.
timestamp

Identifies the date and time (UTC) at which the revision was created.

Behavioural History

Events the activity has originated (e.g. responses such as clicks and opens) can be accessed through the activity's subject feed, located at: /admin/api/<organization-id>/activity/<activity-id>/subject-feed (and provided in the subject-feed-href attribute on the activity element obtained via the XML interface).

The format of this behavioural history is described in the Event Feed Resource section.

Audit Log

Events affecting the activity (i.e. administrative actions such as creation and modification) can be accessed through the activity's object feed, located at: /admin/api/<organization-id>/activity/<activity-id>/object-feed (and provided in the object-feed-href attribute on the activity element obtained via the XML interface).

The format of this audit log is described in the Event Feed Resource section.

JSON Request/Response

When submitted or retrieved using the application/json content type (in the Accept or Content-Type headers), activity records are formatted as follows:

[
   {
      status: null,
      name: 'Test Activity 1',
      subtype: null,
      data: null,
      campaign_id: 1,
      template_id: 1,
      organization_id: 1,
      target_lists: null,
      target_views: null,
      type: 'broadcast',
      date: null,
      throttle: 0,
      revisions: [
         {
            content: '<edition><channel/></edition>',
            combinations: [
               {
                  id: 1,
                  fragment_ids: '1|2|3'
               }
            ],
            id: 1,
            template_revision_id: 2,
            approval_status: null,
            timestamp: '2010-04-10T03:44:10'
         },
         {
            content: '<edition><channel2/></edition>',
            combinations: [
               {
                  id: 2,
                  fragment_ids: '1|2|4'
               }
            ],
            id: 2,
            template_revision_id: 2,
            approval_status: 'approved',
            timestamp: '2010-04-10T03:44:20'
         }
      ],
      ref: null,
      id: 1,
      approval_status: null
   }
]

XML Request/Response

When submitted or retrieved using the application/xml content type (in the Accept or Content-Type headers), activity records are formatted as follows:

<activities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <activity href="/admin/api/1/activity/1" object-feed-href="/admin/api/1/activity/1/object-feed" subject-feed-href="/admin/api/1/activity/1/subject-feed" id="1">
    <name>Test Activity 1</name>
    <type>broadcast</type>
    <subtype xsi:nil="true"/>
    <status xsi:nil="true"/>
    <target-lists xsi:nil="true"/>
    <target-views xsi:nil="true"/>
    <approval-status xsi:nil="true"/>
    <date xsi:nil="true"/>
    <throttle>0</throttle>
    <data xsi:nil="true"/>
    <organization id="1" href="/admin/api/1/organization"/>
    <campaign id="1" href="/admin/api/1/campaign/1"/>
    <template id="1" href="/admin/api/1/template/1"/>
    <revisions>
      <revision id="1" template-revision-id="2">
        <content>
          <edition>
            <channel/>
          </edition>
        </content>
        <combinations>
          <combination id="1" fragment-ids="1|2|3"/>
        </combinations>
        <timestamp>2010-04-10T03:44:10</timestamp>
      </revision>
      <revision id="2" template-revision-id="2" approval-status="approved">
        <content>
          <edition>
            <channel2/>
          </edition>
        </content>
        <combinations>
          <combination id="2" fragment-ids="1|2|4"/>
        </combinations>
        <timestamp>2010-04-10T03:44:20</timestamp>
      </revision>
    </revisions>
  </activity>
</activities>

Campaign Resource

Campaigns provide a way to organise activities, and support higher-level tracking (including conversion tracking).

This API is primarily intended for use by the administrative interface; it is not typically used by third-party systems, but is nevertheless a public interface.

The URI of a campaign record request is similar to:

https://edm2.taguchimail.com/admin/api/<organization-id>/campaign/<campaign-id>

where <organization-id> is the numeric ID of the organization to which the campaign belongs (this will be allocated when an organization is created), and <campaign-id> is the numeric ID of the campaign record to retrieve.

A campaign query URI looks like:

https://edm2.taguchimail.com/admin/api/<organization-id>/campaign/?query=<query>

where <query> is structured as described under Queries in the Introduction section.

Operations

Campaign resources support the following operations, specified either via the HTTP method (GET, PUT, POST, DELETE) or via the _method query-string parameter if the HTTP method cannot be changed:

GET

Retrieves an individual record (if the activity ID is present in the URI), or a list of records (using the query options described under Queries in the Introduction section).
PUT

Updates an individual record; requires the campaign ID be present in the URI.
POST

Creates a new campaign record; requires that no campaign ID be present in the URI.
DELETE

Removes a campaign record; requires that a campaign ID be present in the URI.

Common Fields

id

Unique integer value used to identify the campaign record within TaguchiMail. IDs are consistent for the life of a campaign record, and cannot be changed or assigned.
ref

User-definable unique text field intended to store external primary keys. This value can be updated at any time.
name

The name used to identify the campaign in the Taguchi UI.
date

Indicates the start of the campaign for reporting purposes.
success-event

Links the campaign to its 'success event', determining which event is considered a conversion for this campaign.
status

If set to 'deleted', the campaign will not appear in the UI, and will not be returned in response to API requests.
data

Arbitrary, user-definable campaign data.
organization

Links the campaign to the organization that owns it.

Behavioural History

Events the campaign has originated (e.g. responses such as clicks and opens) can be accessed through the campaign's subject feed, located at: /admin/api/<organization-id>/campaign/<campaign-id>/subject-feed (and provided in the subject-feed-href attribute on the campaign element obtained via the XML interface).

The format of this behavioural history is described in the Event Feed Resource section.

Audit Log

Events affecting the campaign (i.e. administrative actions such as creation and modification) can be accessed through the campaign's object feed, located at: /admin/api/<organization-id>/campaign/<campaign-id>/object-feed (and provided in the object-feed-href attribute on the campaign element obtained via the XML interface).

The format of this audit log is described in the Event Feed Resource section.

JSON Request/Response

When submitted or retrieved using the application/json content type (in the Accept or Content-Type headers), campaign records are formatted as follows:

[
   {
      status: null,
      name: 'Test Campaign 1',
      ref: 'campaign-1',
      organization_id: 1,
      date: null,
      success_event_ref: 's',
      data: null,
      id: 1
   }
]

XML Request/Response

When submitted or retrieved using the application/xml content type (in the Accept or Content-Type headers), campaign records are formatted as follows:

<campaigns xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <campaign href="/admin/api/1/campaign/1" ref="campaign-1" object-feed-href="/admin/api/1/campaign/1/object-feed" subject-feed-href="/admin/api/1/campaign/1/subject-feed" id="1">
    <name>Test Campaign 1</name>
    <status xsi:nil="true"/>
    <date xsi:nil="true"/>
    <data xsi:nil="true"/>
    <organization id="1" href="/admin/api/1/organization"/>
    <activities href="/admin/api/1/activity/?query=campaign_id-eq-1"/>
    <success-event ref="s" href="/admin/api/1/event/s"/>
  </campaign>
</campaigns>

Subscriber Resource

Subscriber records contain the details of an individual recipient of communications (email, direct mail, SMS, and so forth); typically this includes one or more addresses along with supporting information such as first and last names, date of birth, and other user-defined data.

Subscriber records offer a number of mechanisms by which additional user-defined information can be stored:

The 'extra' and 'notifications' fields may contain UTF-8 encoded textual data of any length, for example a JSON data structure. These elements are accessible by variable substitution tokens in the body of a message, and can be updated by subscription management forms.
The 'data' field may contain an arbitrary (valid!) XML document. This document may be updated by API requests or subscription management forms, but is not accessible from variable substition tokens.
The 'custom' field may contain a series of key/value pairs, where both keys and values are textual data. These fields can be accessed within variable substitution tokens, and can also be updated by subscription management forms and API requests. Form submissions may also include uploaded files for custom elements; in this case, the file will be stored on the Taguchi server and the value will be the public URI of the uploaded file.

Subscribers may also belong to zero or more subscriber lists; lists define groups of subscribers who have asked to receive specific content by email, SMS or another 'push' medium. Subscriber list entries track the date and time at which the subscriber was last added to a list, and the date and time at which the subscriber unsubscribed from the list.

The URI of a subscriber record request is similar to:

https://edm2.taguchimail.com/admin/api/<organization-id>/subscriber/<subscriber-id>

Where <organization-id> is the numeric ID of the organization to which the subscriber belongs (this will be allocated when an organization is created), and <subscriber-id> is the numeric ID of the subscriber record to retrieve.

A subscriber query URI looks like:

https://edm2.taguchimail.com/admin/api/<organization-id>/subscriber/?query=<query>

Where <query> is structured as described under Queries in the Introduction section.

Operations

Subscriber resources support the following operations, specified either via the HTTP method (GET, PUT, POST) or via the _method query-string parameter if the HTTP method cannot be changed:

GET

Retrieves an individual record (if the subscriber ID is present in the URI), or a list of records (using the query options described in the Introduction section).
PUT

Updates an individual record; requires the subscriber ID be present in the URI.
POST

Creates a new subscriber record; requires that no subscriber ID be present in the URI.
CREATEORUPDATE

If a matching subscriber record (by external ID or email address) is found, updates that existing record with the submitted data; if no matching record is found, creates a new record. Requires that no subscriber ID be present in the URI.

Common Fields

id

Unique integer value used to identify the subscriber record within TaguchiMail. IDs are consistent for the life of a subscriber record, and cannot be changed or assigned.
ref

User-definable unique text field intended to store external primary keys. This value can be updated at any time.
title

Salutation, e.g. 'Mr', 'Ms'.
firstname

First name. When accessed from variable substitution tokens, the first letter is always uppercase.
lastname

Last name. When accessed from variable substitution tokens, the first letter is always uppercase.
notifications

Arbitrary textual data.
extra

Arbitrary textual data.
phone

Landline phone number. May be any format; validation rules must be enforced by the client system.
mobile

Mobile phone number. May be any format; validation rules must be enforced by the client system.
dob

Date of birth. No timezone is stored.
address

Postal address line 1.
address2

Postal address line 2.
address3

Postal address line 3.
suburb

Postal address suburb/city.
state

Postal address state or province (if applicable).
country

Postal address country. May be full name or ISO code, validation must be performed by the client system.
postcode

Postal code (ZIP code). Validation must be performed by the client system.
gender

Gender; typically either 'M' or 'F' but validation must be performed by the client system.
email

Email address. May be any length; while syntax validation must be performed by the user, Taguchi will automatically identify invalid addresses after an attempt to deliver mail, and will set the 'bounced' flag if it determines that the address is invalid.
unsubscribed

Date and time (UTC) at which the subscriber opted out of all further communications. This flag can be set by the unsubscribe form tracker, the unsubscribe link tracker, the Taguchi UI, the subscription management system, or an API request. Once set, it can only be cleared by an API request or by Taguchi Support. Subscribers with the 'unsubscribed' flag set will never be contacted by the system, but may continue to request content (View Online links in emails, or web pages).
bounced

Date and time (UTC) at which the subscriber's email address was determined to be invalid. This flag is automatically set by TaguchiMail, but can also be set via the Taguchi UI or API requests. Once set, it can only be cleared by an API request or by Taguchi Support. Subscribers with the 'bounced' flag will never be emailed by the system.
data

Arbitrary, user-definable subscriber data in valid XML format.
organization

Links the subscriber to the organization that owns it. This field is not writable.
user-class

If the subscriber is a valid user of the Taguchi system, this will identify the user's level of access. This field is not writable.
campaign

If the subscriber was added to the database as a result of a campaign, this field will identify the campaign. This field is not writable.
import

If the subscriber was added to the database as a result of an import, this field will identify that import. This field is not writable.
cluster

The cluster with which the subscriber is most strongly identified.

Custom Fields

Subscriber custom fields contain a key and a value; keys are unique per subscriber, and fields can be created or updated at any time. Once created, a field cannot be deleted (but its value can be set to null).

If there are no custom fields to submit, set the custom_fields value to an empty list instead of a null value (e.g. custom_fields: []).

List Memberships

Subscriber list memberships may be created or updated at any time, but a list membership can never be deleted. List memberships have the following fields:

list

Identifies the ID of the list to which the membership relates.
import

If the list membership was created as a result of an import, this field identifies the import. This field is not writable.
campaign

If the list membership was created as a result of a campaign, this field identifies the campaign. This field is not writable.
timestamp

Identifies the date and time (UTC) at which the membership was created. This field is not writable.
unsubscribed

If the subscriber's list membership is not active, this field contains the date and time (UTC) at which the subscriber left the list.
option

This field contains arbitrary textual data, and can be used for segmentation, personalization or as an identifier linking to a client system.

Behavioural History

Events the subscriber has originated (e.g. responses such as clicks and opens) can be accessed through the subscriber's subject feed, located at: /admin/api/<organization-id>/subscriber/<subscriber-id>/subject-feed (and provided in the subject-feed-href attribute on the subscriber element obtained via the XML interface).

The format of this behavioural history is described in the Event Feed Resource section.

Audit Log

Events affecting the subscriber (i.e. administrative actions such as creation and modification) can be accessed through the subscriber's object feed, located at: /admin/api/<organization-id>/subscriber/<subscriber-id>/object-feed (and provided in the object-feed-href attribute on the subscriber element obtained via the XML interface).

The format of this audit log is described in the Event Feed Resource section.

JSON Request/Response

When submitted or retrieved using the application/json content type (in the Accept or Content-Type headers), subscriber records are formatted as follows:

[
   {
      import_id: null,
      cluster_id: null,
      firstname: 'Example',
      extra: null,
      lastname: 'Person',
      address2: null,
      address3: null,
      campaign_id: null,
      lists: [
         {
            import_id: null,
            option: null,
            timestamp: '2010-04-11T00:00:00',
            campaign_id: null,
            unsubscribed: null,
            list_id: 5
         },
         {
            import_id: null,
            option: null,
            timestamp: '2010-04-11T00:00:00',
            campaign_id: null,
            unsubscribed: '2010-04-12T00:00:00',
            list_id: 6
         }
      ],
      organization_id: 1,
      phone: '0400312312',
      suburb: null,
      postcode: '3000',
      address: null,
      data: null,
      id: 2,
      custom_fields: [
         {
            field: 'examplekey',
            data: 'val'
         }
      ],
      bounced: null,
      title: 'Mr',
      dob: '1970-04-01',
      user_class_id: 1,
      state: null,
      unsubscribed: null,
      gender: 'M',
      country: 'AU',
      ref: null,
      email: 'person@example.org',
      notifications: null
   }
]

XML Request/Response

When submitted or retrieved using the application/xml content type (in the Accept or Content-Type headers), subscriber records are formatted as follows:

<subscribers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <subscriber href="/admin/api/1/subscribers/3" object-feed-href="/admin/api/1/subscribers/3/object-feed" subject-feed-href="/admin/api/1/subscribers/3/subject-feed" id="3">
    <title>Ms</title>
    <firstname>Example</firstname>
    <lastname>Person</lastname>
    <notifications xsi:nil="true"/>
    <extra xsi:nil="true"/>
    <phone>0400312312</phone>
    <dob xsi:nil="true"/>
    <address>1 Collins St</address>
    <address2 xsi:nil="true"/>
    <address3 xsi:nil="true"/>
    <suburb>Melbourne</suburb>
    <state>VIC</state>
    <country>AU</country>
    <postcode>3000</postcode>
    <gender>F</gender>
    <email>person@example.org</email>
    <unsubscribed>2010-04-02T00:00:00</unsubscribed>
    <bounced xsi:nil="true"/>
    <data xsi:nil="true"/>
    <organization id="1" href="/admin/api/1/organization"/>
    <user-class id="1" href="/admin/api/1/user-class/1"/>
    <campaign xsi:nil="true" href=""/>
    <import xsi:nil="true" href=""/>
    <cluster xsi:nil="true" href=""/>
    <lists>
      <list id="1" href="/admin/api/1/list/1">
        <import xsi:nil="true" href=""/>
        <campaign xsi:nil="true" href=""/>
        <timestamp>2010-04-13T04:49:56</timestamp>
        <unsubscribed xsi:nil="true"/>
        <option xsi:nil="true"/>
      </list>
      <list id="2" href="/admin/api/1/list/2">
        <import xsi:nil="true" href=""/>
        <campaign xsi:nil="true" href=""/>
        <timestamp>2010-04-13T04:49:56</timestamp>
        <unsubscribed>2010-04-13T04:49:59</unsubscribed>
        <option xsi:nil="true"/>
      </list>
    </lists>
    <custom-fields>
      <custom field="examplekey">value</custom>
    </custom-fields>
  </subscriber>
</subscribers>

List Resource

Lists are used to manage opt-in preferences for subscribers in the Taguchi database.

This API is primarily intended for use by the administrative interface; it is not typically used by third-party systems, but is nevertheless a public interface.

The URI of a list record request is similar to:

https://edm2.taguchimail.com/admin/api/<organization-id>/list/<list-id>

where <organization-id> is the numeric ID of the organization to which the list belongs (this will be allocated when an organization is created), and <list-id> is the numeric ID of the list record to retrieve.

A list query URI looks like:

https://edm2.taguchimail.com/admin/api/<organization-id>/list/?query=<query>

where <query> is structured as described under Queries in the Introduction section.

Operations

List resources support the following operations, specified either via the HTTP method (GET, PUT, POST, DELETE) or via the _method query-string parameter if the HTTP method cannot be changed:

GET

Retrieves an individual record (if the activity ID is present in the URI), or a list of records (using the query options described in the Introduction section).
PUT

Updates an individual record; requires the list ID be present in the URI.
POST

Creates a new list record; requires that no list ID be present in the URI.
DELETE

Removes a list record; requires that a list ID be present in the URI.
EXTRACT

Runs a list extract; should be implemented as HTTP POST with _method=EXTRACT. Accepts the following query parameters:
Show Parameters
- notify
  
  List ID of the notification list to which the extract completion notification will be sent (if not present, the extract completion notification will be sent to the user which performed the extract command).
- query
  
  As with the query options described in the Introduction section), this parameter determines which subscribers are included in the extract.

Common Fields

id

Unique integer value used to identify the list record within TaguchiMail. IDs are consistent for the life of a list record, and cannot be changed or assigned.
ref

User-definable unique text field intended to store external primary keys. This value can be updated at any time.
name

The name used to identify the list in the Taguchi UI.
timestamp

The date and time (UTC) at which the list was created.
status

If set to 'deleted', the list will not appear in the UI, and will not be returned in response to API requests.
data

Arbitrary, user-definable list data.
organization

Links the list to the organization that owns it.

Audit Log

Events affecting the list (i.e. administrative actions such as creation and modification) can be accessed through the list's object feed, located at: /admin/api/<organization-id>/list/<list-id>/object-feed (and provided in the object-feed-href attribute on the list element obtained via the XML interface).

The format of this audit log is described in the Event Feed Resource section.

JSON Request/Response

When submitted or retrieved using the application/json content type (in the Accept or Content-Type headers), list records are formatted as follows:

[
   {
      status: null,
      organization_id: 1,
      ref: 'notifications.tm',
      name: 'Notifications - Taguchi Support',
      timestamp: '2010-04-14T17:23:44',
      data: null,
      id: 3
   }
]

XML Request/Response

When submitted or retrieved using the application/xml content type (in the Accept or Content-Type headers), list records are formatted as follows:

<lists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <list href="/admin/api/1/list/3" id="3" ref="notifications.tm">
    <name>Notifications - Taguchi Support</name>
    <timestamp>2010-04-14T17:23:44</timestamp>
    <data xsi:nil="true"/>
    <organization id="1" href=""/>
    <status xsi:nil="true"/>
    <subscribers href="/admin/api/1/subscriber/?query=list_id-eq-3"/>
  </list>
</lists>

Import Resource

The import element represents an import record in the Taguchi database. Import records store file URIs, column/field mappings and encoding information for subscriber database imports.

Imports that have started processing track the number of subscriber records created in statistics fields; these provide an indication of the overall progress of the import.

This API is primarily intended for use by the administrative interface; it is not typically used by third-party systems, as systems requiring regular imports or exports are normally scheduled via Taguchi Support.

The URI of an import record request is similar to:

https://edm2.taguchimail.com/admin/api/<organization-id>/import/<import-id>

where <organization-id> is the numeric ID of the organization to which the import belongs (this will be allocated when an organization is created), and <import-id> is the numeric ID of the import record to retrieve.

A import query URI looks like:

https://edm2.taguchimail.com/admin/api/<organization-id>/import/?query=<query>

where <query> is structured as described under Queries in the Introduction section.

Operations

Import resources support the following operations, specified either via the HTTP method (GET, PUT, POST, DELETE) or via the _method query-string parameter if the HTTP method cannot be changed:

GET

Retrieves an individual record (if the activity ID is present in the URI), or a list of records (using the query options described in the Introduction section).
PUT

Updates an individual record; requires the import ID be present in the URI.
POST

Creates a new import record; requires that no import ID be present in the URI.
DELETE

Removes a import record; requires that a import ID be present in the URI.
PROCESS

Starts processing an import; requires that a import ID be present in the URI. Should be implemented as an HTTP GET or POST with _method=PROCESS.

Common Fields

id

Unique integer value used to identify the import record within TaguchiMail. IDs are consistent for the life of an import, and cannot be changed or assigned.
ref

User-definable unique text field intended to store external primary keys. This value can be updated at any time.
name

The name used to identify the import in the Taguchi UI.
source

A description of the source of the subscribers in the import, for audit purposes.
timestamp

Indicates the date and time (UTC) at which the import processing started.
manifest

XML document describing the import processing rules: input file formats, input URIs, destination subscriber lists, encodings, and column/field mappings.
status

If set to 'deleted', the import will not appear in the UI, and will not be returned in response to API requests.
params

Arbitrary, user-definable import data.
organization

Links the import to the organization that owns it.

Manifest

The import manifest is an XML document detailing the import file URI(s), field assignments, formats, and destination lists. An example is shown below:

<manifest xmlns="http://taguchimail.com/manifest" import-id="1">
    <source href="file:///tmp/example.tsv">
        <format type="delimited" field-separator="\t" line-separator="\n" />
        <fields>
            <field name="email" select="@0" />
            <field name="firstname" select="@1" />
            <field name="lastname" select="@2" />
        </fields>
        <lists>
            <list id="1"/>
        </lists>
    </source>
</manifest>

This manifest imports a delimited file from the source file:///tmp/example.tsv (mapping to /tmp/example.tsv on the Taguchi server's local drive), with fields separated by tab characters (\t) and lines separated by newline characters (\n). Any character sequences may be used as field and line separators; these should be specified with C-style escape codes if necessary.

The fields to be imported are described by field elements; in the above example they are email, firstname and lastname. Any fields available in subscriber records may be imported. The field selectors are of the form "@n", where n is the index of the field in the file (starting at 0 for the leftmost field).

After importing the subscribers, they are added to the lists specified in the lists element; in the above case, List ID 1.

Manifests are often generated by the Taguchi UI, but can be specified via APIs if necessary. The basic structure must be as above, but the following additional options are supported:

source elements may be repeated within the manifest, each one specifying a different source file using the href attribute. The value of the href attribute may be any valid local, HTTP, HTTPS or FTP URI (with inline authentication credentials if necessary).
format elements require a type attribute, which may be either delimited (for delimited files as exported by Excel and most database packages) or xml (for XML databases). If the type is delimited, the attributes field-separator and line-separator are required, and specify the field and line separator sequences respectively. If the type is xml, the select attribute is required; this attribute must be an XPath which selects the individual subscriber records from the XML database.
The fields element must contain a series of field elements, each of which has name and select attributes. Field name attributes correspond to the defined subscriber resource fields; if custom fields are desired they must be named "custom_x" where x is the name of the custom field. If the format is delimited, the select attribute is "@n", where n is the column index from which field values should be taken; if the format is xml, the select attribute is an XPath which is evaluated relative to the subscriber record node, and which must select the appropriate value for that field.
The lists element may contain one or more list elements, each of which has an id attribute; the value of this attribute specifies a list to which subscribers in this import should be added.

Audit Log

Events affecting the import (i.e. administrative actions such as creation and modification) can be accessed through the import's object feed, located at: /admin/api/<organization-id>/import/<import-id>/object-feed (and provided in the object-feed-href attribute on the import element obtained via the XML interface).

The format of this audit log is described in the Event Feed Resource section.

JSON Request/Response

When submitted or retrieved using the application/json content type (in the Accept or Content-Type headers), import records are formatted as follows:

[
   {
      status: null,
      total: 0,
      list_new: 0,
      name: 'Test Import 1',
      timestamp: null,
      invalid: 0,
      manifest: '<manifest xmlns="dummy"><source/></manifest>',
      organization_id: 1,
      source: null,
      global_new: 0,
      bounced: 0,
      ref: null,
      id: 1
   }
]

XML Request/Response

When submitted or retrieved using the application/xml content type (in the Accept or Content-Type headers), import records are formatted as follows:

<imports xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <import href="/admin/api/1/import/1" object-feed-href="/admin/api/1/import/1/object-feed" id="1">
    <name>Test Import 1</name>
    <timestamp xsi:nil="true"/>
    <manifest>
      <manifest xmlns="dummy">
        <source/>
      </manifest>
    </manifest>
    <status xsi:nil="true"/>
    <organization id="1" href="/admin/api/1/organization"/>
    <total>0</total>
    <invalid>0</invalid>
    <bounced>0</bounced>
    <global-new>0</global-new>
    <list-new>0</list-new>
  </import>
</imports>

View Resource

View records provide the ability to define SQL constraints which can be applied to email or SMS distribution lists, restricting distribution to a subset of the list based on some arbitrary criterion.

For instance, a view could target all subscribers on a list in a particular state, all subscribers on a list but not on some other list, or all subscribers on a list who have clicked a specific list in the past.

This API is primarily intended for use by the administrative interface; it is not typically used by third-party systems, but is nevertheless a public interface.

The URI of a campaign record request is similar to:

https://edm2.taguchimail.com/admin/api/<organization-id>/view/<view-id>

Where <organization-id> is the numeric ID of the organization to which the view belongs (this will be allocated when an organization is created), and <view-id> is the numeric ID of the view record to retrieve.

A view query URI looks like:

https://edm2.taguchimail.com/admin/api/<organization-id>/view/?query=<query>

Where <query> is structured as described under Queries in the Introduction section.

Operations

View resources support the following operations, specified either via the HTTP method (GET, PUT, POST, DELETE) or via the _method query-string parameter if the HTTP method cannot be changed:

GET

Retrieves an individual record (if the activity ID is present in the URI), or a list of records (using the query options described in the Introduction section).
PUT

Updates an individual record; requires the view ID be present in the URI.
POST

Creates a new view record; requires that no view ID be present in the URI.
DELETE

Removes a view record; requires that a view ID be present in the URI.

Common Fields

id

Unique integer value used to identify the campaign record within TaguchiMail. IDs are consistent for the life of a view record, and cannot be changed or assigned.
ref

User-definable unique text field intended to store external primary keys. This value can be updated at any time.
name

The name used to identify the view in the Taguchi UI.
constraint

The SQL constraint used to determine whether a subscriber matches the view.
status

If set to 'deleted', the view will not appear in the UI, and will not be returned in response to API requests.
organization

Links the view to the organization that owns it.

Audit Log

Events affecting the view (i.e. administrative actions such as creation and modification) can be accessed through the view's object feed, located at: /admin/api/<organization-id>/view/<view-id>/object-feed (and provided in the object-feed-href attribute on the view element obtained via the XML interface).

The format of this audit log is described in the Event Feed Resource section.

JSON Request/Response

When submitted or retrieved using the application/json content type (in the Accept or Content-Type headers), view records are formatted as follows:

[
   {
      status: null,
      organization_id: 1,
      predicate: 's.state = \'VIC\'',
      name: 'Example View',
      ref: null,
      id: 1
   }
]

XML Request/Response

When submitted or retrieved using the application/xml content type (in the Accept or Content-Type headers), view records are formatted as follows:

<views xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <view href="/admin/api/1/view/1" id="1" object-feed-href="/admin/api/1/view/1/object-feed-href">
    <name>Example View</name>
    <predicate>s.state = 'VIC'</predicate>
    <organization id="1" href="/admin/api/1/organization"/>
    <status xsi:nil="true"/>
  </view>
</views>

Event Resource

Events provide names, descriptions and priority values to the event references used when logging subscriber actions.

This API is primarily intended for use by the administrative interface; it is not typically used by third-party systems. The events API does not support the creation or alteration of events; if this is required, please contact Taguchi Support.

The URI of an event record request is similar to:

https://edm2.taguchimail.com/admin/api/<organization-id>/event/<event-id>

Where <organization-id> is the numeric ID of the organization to which the event belongs (this will be allocated when an organization is created), and <event-id> is the text ID of the event record to retrieve.

A event query URI looks like:

https://edm2.taguchimail.com/admin/api/<organization-id>/event/?query=<query>

Where <query> is structured as described under Queries in the Introduction section.

Operations

Event resources support the following operations, specified either via the HTTP method (GET, PUT, POST, DELETE) or via the _method query-string parameter if the HTTP method cannot be changed:

GET

Retrieves an individual record (if the activity ID is present in the URI), or a list of records (using the query options described in the Introduction section).

Common Fields

ref

Primary key of the table; referenced by subscriber events and also campaigns (through the success-event element).
name

The name used to identify the event in the Taguchi UI.
description

Indicates the start of the campaign for reporting purposes.
priority

The priority level for this event, which controls which trigger processing stream the event uses (currently priorities 0, 1 and 2 are defined). All events within a priority group will be processed on a first-in, first-out basis. If null, triggers will not be processed for the event type.

JSON Request/Response

When submitted or retrieved using the application/json content type (in the Accept or Content-Type headers), event records are formatted as follows:

[
   {
      priority: null,
      ref: 's',
      name: 'Sent',
      description: 'Logged each time an email, SMS, fax, phone call, or DM is sent to a subscriber.'
   }
]

XML Request/Response

When submitted or retrieved using the application/xml content type (in the Accept or Content-Type headers), event records are formatted as follows:

<events xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <event href="/admin/api/1/event/s" ref="s">
    <name>Sent</name>
    <description>Logged each time an email, SMS, fax, phone call, or DM is sent to a subscriber.</description>
    <priority xsi:nil="true"/>
  </event>
</events>

Example Requests

Retrieve a single event record

Request:

GET /admin/api/1/event/s?auth=example@taguchimail.com|password HTTP/1.1
Host: edm2.taguchimail.com
Accept: application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Accept-Language: en-us
Accept-Encoding: gzip, deflate

Response:

HTTP/1.1 200 OK
Content-Length: 330
Content-Type: application/xml; charset=UTF-8

<events xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <event href="/admin/api/1/event/s" ref="s">
    <name>Sent</name>
    <description>Logged each time an email, SMS, fax, phone call, or DM is sent to a subscriber.</description>
    <priority xsi:nil="true"/>
  </event>
</events>

Search for all events with ref starting with aa

Request:

GET /admin/api/1/event/?auth=example@taguchimail.com|password&query=ref-like-aa% HTTP/1.1
Host: edm2.taguchimail.com
Accept: application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Accept-Language: en-us
Accept-Encoding: gzip, deflate

Response:

HTTP/1.1 200 OK
Content-Length: 1932
Content-Type: application/xml; charset=UTF-8

<events xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <event href="/admin/api/1/event/aaa" ref="aaa">
    <name>Approved Activity</name>
    <description></description>
    <priority>0</priority>
  </event>
  <event href="/admin/api/1/event/aac" ref="aac">
    <name>Created Activity</name>
    <description></description>
    <priority>1</priority>
  </event>
  <event href="/admin/api/1/event/aad" ref="aad">
    <name>Deleted Activity</name>
    <description></description>
    <priority>1</priority>
  </event>
  <event href="/admin/api/1/event/aae" ref="aae">
    <name>Requested Approval for Activity</name>
    <description></description>
    <priority>0</priority>
  </event>
  <event href="/admin/api/1/event/aal" ref="aal">
    <name>Viewed Activity List</name>
    <description></description>
    <priority>1</priority>
  </event>
  <event href="/admin/api/1/event/aao" ref="aao">
    <name>Commented on Activity</name>
    <description></description>
    <priority>0</priority>
  </event>
  <event href="/admin/api/1/event/aap" ref="aap">
    <name>Proofed Activity</name>
    <description></description>
    <priority>0</priority>
  </event>
  <event href="/admin/api/1/event/aaq" ref="aaq">
    <name>Queued Activity</name>
    <description></description>
    <priority>2</priority>
  </event>
  <event href="/admin/api/1/event/aar" ref="aar">
    <name>Rejected Activity</name>
    <description></description>
    <priority>0</priority>
  </event>
  <event href="/admin/api/1/event/aat" ref="aat">
    <name>Triggered Activity</name>
    <description></description>
    <priority>0</priority>
  </event>
  <event href="/admin/api/1/event/aau" ref="aau">
    <name>Updated Activity</name>
    <description></description>
    <priority>1</priority>
  </event>
  <event href="/admin/api/1/event/aav" ref="aav">
    <name>Viewed Activity</name>
    <description></description>
    <priority>1</priority>
  </event>
</events>

Event Feed Resource

Event feeds provide access to Taguchi's logging system, which tracks subscriber and user behaviour. Most Taguchi resource types have an "object feed", which contains an audit log of actions which have been performed on individual records, and some resources also have a "subject feed", which contains a behavioural history of actions which have been performed by (or as a result of) an individual record.

In addition to the distinction between actions a record performed, and actions performed on a record, Taguchi distinguishes between events which have occurred (logged events), and events which will occur one or more times in the future (scheduled events). When a scheduled event is due to occur, it becomes a logged event, and the event handler scripts appropriate to its event type are executed.

Taguchi tracks causal relationships between events, so when an event can be said to have occurred due to another event (e.g. an email being opened, which occurred because the email was first sent), the causing event becomes the caused event's parent (set in the parent field).

Event feeds are read-only resources, however some event types can be caused via the Taguchi public interfaces. Events can never be changed once logged, although custom data can be added to an event via the annotation form interface.

Operations

Event feeds support the following operations, specified either via the HTTP method (GET, PUT, POST) or via the _method query-string parameter if the HTTP method cannot be changed:

GET

Retrieves a list of records using the query options described under Queries in the Introduction section.

Common Fields

type

Either logged or scheduled depending on whether the event has already occurred, or is scheduled to occur.
id

The event token, which uniquely identifies the event in the Taguchi system.
test

If true, this event and all events it causes will be regarded as tests, and will not contribute to statistics tracking.
parent

The event token of the event which directly caused/preceded this event.
event_ref

The code describing the action this event represents, corresponding to the ref field in the Event Resource.
subscriber

The ID of the subscriber which initiated this event.
activity

The ID of the activity which initiated this event, if any.
revision

The ID of the activity revision which initiated this event, if any.
configuration

The ID of the activity revision configuration which initiated this event, if any.
campaign

The ID of the campaign to which this event was credited, if any.
trackurl

The ID of the tracking link which this event accessed, if any.
trackurl_index

The link index of the tracking link accessed by this event, if any. The first instance of a particular link in a message will be index 0, the second instance will be index 1, and so forth.
trackurl_destination

The destination URI of the tracking link accessed by this event, if any. A single tracking link ID corresponds to a unique (destination, index) pair.
data

A user-defined field containing UTF-8 encoded text of any length.

Logged Event Fields

In addition to the above fields, logged events contain the following:

timestamp

The date and time (UTC) at which this event occurred.
processed

Whether or not the event has had its handler scripts executed.

Scheduled Event Fields

In addition to the common fields above, scheduled events contain the following:

oneshot

If true, this event will be removed from the scheduler once it occurs.
schedule

An RFC 2445 recurrence rule determining the frequency and timing of occurrences of this event.
next_timestamp

The next date and time (UTC) at which this event will occur.
last_timestamp

The last date and time (UTC) at which this event did occur (will be null if the event has never occurred).
start_timestamp

The start date and time (UTC) for processing the schedule rule.

Custom Fields

Event custom fields contain a key and a value; keys are unique per logged or scheduled event, and fields can be created or updated at any time. Once created, a field cannot be deleted (but its value can be set to null). When a scheduled event occurs, the logged event it creates will have the same set of custom fields.

JSON Request/Response

When submitted or retrieved using the application/json content type (in the Accept or Content-Type headers), event feeds are formatted as follows:

[
   {
      type: 'logged',
      id: 123,
      processed: true,
      test: true,
      parent_id: 15,
      event_ref: 'c',
      subscriber_id: 1,
      activity_id: 5,
      revision_id: 4,
      configuration_id: 8,
      campaign_id: 2,
      trackurl_id: 345,
      trackurl_index: 5,
      trackurl_destination: 'http://www.example.org/',
      timestamp: '2010-04-10T04:33:10',
      data: '1234',
      custom_fields: [
         {
            field: 'ip',
            data: '192.168.1.1'
         }
      ]
   },
   {
      type: 'scheduled',
      id: 1,
      test: true,
      parent_id: 123,
      event_ref: 's',
      subscriber_id: 1,
      activity_id: 5,
      revision_id: 4,
      configuration_id: 8,
      campaign_id: 2,
      trackurl_id: null,
      trackurl_index: null,
      trackurl_destination: null,
      data: '1',
      oneshot: true,
      next_timestamp: '2010-04-10T05:33:10',
      last_timestamp: null,
      start_timestamp: '2010-04-10T04:33:10',
      schedule: null,
      custom_fields: [
         {
            field: 'reason',
            data: 'opt-in'
         }
      ]
   }
]

XML Request/Response

When submitted or retrieved using the application/xml content type (in the Accept or Content-Type headers), event feeds are formatted as follows:

<event-feed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <logged-event id="123" processed="true" test="true">
    <parent id="15" href="/admin/api/1/event-feed/?parent_id-eq-15"/>
    <children href="/admin/api/1/event-feed/?parent_id-eq-123"/>
    <event ref="c" href="/admin/api/1/organization/c"/>
    <subscriber id="1" href="/admin/api/1/subscriber/1"/>
    <activity id="5" revision-id="4" configuration-id="8" href="/admin/api/1/activity/5"/>
    <campaign id="2" href="/admin/api/1/campaign/2"/>
    <trackurl id="345" index="5">http://www.example.org/</trackurl>
    <data>1234</data>
    <timestamp>2010-04-10T04:33:10</timestamp>
    <custom-fields>
      <field name="ip">192.168.1.1</field>
    </custom-fields>
  </logged-event>
  <scheduled-event id="1" test="true">
    <parent id="123" href="/admin/api/1/event-feed/?parent_id-eq-123"/>
    <event ref="s" href="/admin/api/1/organization/s"/>
    <subscriber id="1" href="/admin/api/1/subscriber/1"/>
    <activity id="5" revision-id="4" configuration-id="8" href="/admin/api/1/activity/5"/>
    <campaign id="2" href="/admin/api/1/campaign/2"/>
    <trackurl xsi:nil="true"/>
    <data>1</data>
    <oneshot>true</oneshot>
    <next-timestamp>2010-04-10T05:33:10</next-timestamp>
    <last-timestamp xsi:nil="true"/>
    <start-timestamp>2010-04-10T04:33:10</start-timestamp>
    <schedule xsi:nil="true"/>
    <custom-fields>
      <field name="reason">opt-in</field>
    </custom-fields>
  </scheduled-event>
</event-feed>

Template Resource

Template records contain the transform stylesheet and content structure definition for email, SMS, and web page layouts.

Template content and format is stored in a series of revisions, which provide version control functionality.

Aside from its role in the administrative interface, the template API should be used by third-party systems to create and manage email templates.

The URI of a template record request is similar to:

https://edm2.taguchimail.com/admin/api/<organization-id>/template/<template-id>

where <organization-id> is the numeric ID of the organization to which the template belongs (this will be allocated when an organization is created), and <template-id> is the numeric ID of the template record to retrieve.

A template query URI looks like:

https://edm2.taguchimail.com/admin/api/<organization-id>/template/?query=<query>

where <query> is structured as described under Queries in the Introduction section.

Template requests also support a revisions query-string parameter, which determines which of a template's saved revisions are included in the response. The following values are supported:

latest: Returns only the latest revision;
history: Returns the entire revision history.

If the revisions query-string parameter is not set, no revisions are returned.

Operations

Template resources support the following operations, specified either via the HTTP method (GET, PUT, POST, DELETE) or via the _method query-string parameter if the HTTP method cannot be changed:

GET

Retrieves an individual record (if the activity ID is present in the URI), or a list of records (using the query options described under Queries in the Introduction section).
PUT

Updates an individual record; requires the template ID be present in the URI.
POST

Creates a new template record; requires that no template ID be present in the URI.
DELETE

Removes a template record; requires that a template ID be present in the URI.

Common Fields

id

Unique integer value used to identify the template record within TaguchiMail. IDs are consistent for the life of a template record, and cannot be changed or assigned.
ref

User-definable unique text field intended to store external primary keys. This value can be updated at any time.
name

The name used to identify the template in the Taguchi UI.
type

Determines the distribution mechanism for activities using this template; corresponds to the 'type' field in activity records.
subtype

Determines 'suggested' vs 'other' templates in the activity UI; this corresponds to the 'subtype' field in activity records.
status

If set to 'deleted', the template will not appear in the UI, and will not be returned in response to API requests.
data

Arbitrary, user-definable template data.
organization

Links the template to the organization that owns it.

Revisions

Template content is stored as a series of revisions, each of which is timestamped. By default, revision content is not returned in template responses, however the revisions to return can be controlled using the revisions query-string parameter (set to either history or latest as described above).

Revisions contain the following fields:

id

ID of the revision record in the database.
content

Contains the revision XSLT stylesheet. This is normally created within the Taguchi UI, and is designed to work with the XML documents created by the activity edit interface; these are created based on the format field, which defines allowable data types and document structure.
format

Contains the revision's Data Description, which controls the form interface created by Taguchi to edit activities using this template. This document indirectly determines the structure of the source document used by the template's stylesheet.
timestamp

Identifies the date and time (UTC) at which the revision was created.

Audit Log

Events affecting the template (i.e. administrative actions such as creation and modification) can be accessed through the template's object feed, located at: /admin/api/<organization-id>/template/<template-id>/object-feed (and provided in the object-feed-href attribute on the template element obtained via the XML interface).

The format of this audit log is described in the Event Feed Resource section.

JSON Request/Response

When submitted or retrieved using the application/json content type (in the Accept or Content-Type headers), template records are formatted as follows:

[
   {
      status: null,
      name: 'Test Template 1',
      data: null,
      organization_id: 1,
      subtype: null,
      type: 'broadcast',
      ref: null,
      id: 1,
      revisions: [
         {
            content: '<abc></abc>',
            id: 1,
            format: '<def></def>',
            timestamp: '2010-04-10T03:44:10'
         },
         {
            content: '<abc></abc>',
            id: 2,
            format: '<def></def>',
            timestamp: '2010-04-10T03:44:20'
         }
      ]
   }
]

XML Request/Response

When submitted or retrieved using the application/xml content type (in the Accept or Content-Type headers), template records are formatted as follows:

<templates xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://taguchimail.com/api">
  <template id="1" href="/admin/api/1/template/1" object-feed-href="/admin/api/1/template/1/object-feed-href">
    <name>Test Template 1</name>
    <type>broadcast</type>
    <subtype xsi:nil="true"/>
    <status xsi:nil="true"/>
    <data xsi:nil="true"/>
    <organization id="1" href="/admin/api/1/organization"/>
    <activities href="/admin/api/1/activity/?template_id-eq-1"/>
    <revisions>
      <revision id="1">
        <content>
          <abc/>
        </content>
        <format>
          <def/>
        </format>
        <timestamp>2010-04-10T03:44:10</timestamp>
      </revision>
      <revision id="2">
        <content>
          <abc/>
        </content>
        <format>
          <def/>
        </format>
        <timestamp>2010-04-10T03:44:20</timestamp>
      </revision>
    </revisions>
  </template>
</templates>

Statistics Resource

Common Query Parameters

start_date

Return statistics gathered on or after a particular date.
end_date

Return statistics gathered on or before a particular date.
period

One or more of day, week, month and all; aggregate returned statistics by that unit of time.

Event Aggregates

event

Specifies an event type to be returned in the query (multiple events may be specified by repeating the event parameter).

Example Query

https://edm2.taguchimail.com/admin/api/1/stats/aggregate?event=s&event=o&event=c&start_date=2010-01-01T00%3A00%3A00&end_date=2010-06-01T00%3A00%3A00&period=week

Example Response (JSON)

{
   "all":{
      "c":[
         ["2010-01-04",10207],
         ["2010-01-11",9679],
         ["2010-01-18",11811],
         ["2010-01-25",13055],
         ["2010-02-01",18018],
         ["2010-02-08",9880],
         ["2010-02-15",9340],
         ["2010-02-22",9982],
         ["2010-03-01",11841],
         ["2010-03-08",12868],
         ["2010-03-15",14342],
         ["2010-03-22",9854],
         ["2010-03-29",12269],
         ["2010-04-05",13447],
         ["2010-04-12",11158],
         ["2010-04-19",11189],
         ["2010-04-26",11966],
         ["2010-05-03",10376],
         ["2010-05-10",16599],
         ["2010-05-17",9260],
         ["2010-05-24",4011]
      ],
      "s":[
         ["2010-01-04",56071],
         ["2010-01-11",52830],
         ["2010-01-18",54439],
         ["2010-01-25",73310],
         ["2010-02-01",55860],
         ["2010-02-08",36676],
         ["2010-02-15",36750],
         ["2010-02-22",35095],
         ["2010-03-01",37296],
         ["2010-03-08",37447],
         ["2010-03-15",57224],
         ["2010-03-22",38627],
         ["2010-03-29",112756],
         ["2010-04-05",38229],
         ["2010-04-12",38507],
         ["2010-04-19",57552],
         ["2010-04-26",76088],
         ["2010-05-03",57401],
         ["2010-05-10",80631],
         ["2010-05-17",35102],
         ["2010-05-24",26919]
      ],
      "o":[
         ["2010-01-04",19327],
         ["2010-01-11",18493],
         ["2010-01-18",20220],
         ["2010-01-25",25300],
         ["2010-02-01",22358],
         ["2010-02-08",15600],
         ["2010-02-15",15013],
         ["2010-02-22",13696],
         ["2010-03-01",15827],
         ["2010-03-08",16239],
         ["2010-03-15",21874],
         ["2010-03-22",18107],
         ["2010-03-29",34553],
         ["2010-04-05",20811],
         ["2010-04-12",17149],
         ["2010-04-19",20391],
         ["2010-04-26",30082],
         ["2010-05-03",20914],
         ["2010-05-10",28000],
         ["2010-05-17",17796],
         ["2010-05-24",6261]
      ]
   }
}

Campaign/Activity Totals

campaign_id

Include one or more campaign_id parameters to restrict the result set to one or more campaigns.
activity_id

If there is no campaign_id parameter, include one or more activity_id parameters to restrict the result set to one or more activities.
revision_id

If there is no activity_id parameter, include one or more revision_id parameters to restrict the result set to one or more revisions.
configuration_id

If there is no revision_id parameter, include one or more configuration_id parameters to restrict the result set to one or more configurations.
granularity

One of campaign, activity, revision, configuration. Determines the extent to which statistics are rolled up, and the result of specifying no campaign_id, activity_id, revision_id or configuration_id; if granularity is campaign, then a query with no restrictions will return all campaigns; if granularity is activity, then a query with no restrictions will return all activities, and so forth.

Example Query

https://edm2.taguchimail.com/admin/api/1/stats/campaign?event=s&event=o&event=c&event=v&event=b&start_date=2010-01-01T00%3A00%3A00&end_date=2010-06-01T00%3A00%3A00&period=all

Example Response (JSON)

{
   "1":{
      "c":[
         ["all",511016]
      ],
      "b":[
         ["all",17681]
      ],
      "s":[
         ["all",2200019]
      ],
      "o":[
         ["all",873079]
      ],
      "v":[
         ["all",20072]
      ]
   },
   "4":{
      "b":[
         ["all",9]
      ],
      "o":[
         ["all",52]
      ]
   },
   "5":{
      "c":[
         ["all",7]
      ],
      "b":[
         ["all",9]
      ],
      "o":[
         ["all",190]
      ]
   },
   "9":{
      "c":[
         ["all",7]
      ],
      "b":[
         ["all",19]
      ],
      "o":[
         ["all",495]
      ],
      "v":[
         ["all",79]
      ]
   }
}

List Aggregates

This interface takes no parameters other than those outlined in Common Query Parameters above.

Example Query

https://edm2.taguchimail.com/admin/api/1/stats/listaggregate?start_date=2010-01-01T00%3A00%3A00&end_date=2010-06-01T00%3A00%3A00&period=week

Example Response (JSON)

{
   "all":{
      "active":[
         ["2010-01-04",-81],
         ["2010-01-11",75],
         ["2010-01-18",-22],
         ["2010-01-25",-25],
         ["2010-02-01",-753],
         ["2010-02-08",-19],
         ["2010-02-15",58],
         ["2010-02-22",88],
         ["2010-03-01",102],
         ["2010-03-08",87],
         ["2010-03-15",82],
         ["2010-03-22",-23],
         ["2010-03-29",5],
         ["2010-04-05",202],
         ["2010-04-12",155],
         ["2010-04-19",205],
         ["2010-04-26",36],
         ["2010-05-03",131],
         ["2010-05-10",767],
         ["2010-05-17",247],
         ["2010-05-24",112]
      ],
      "total":[
         ["2010-01-04",209],
         ["2010-01-11",251],
         ["2010-01-18",145],
         ["2010-01-25",214],
         ["2010-02-01",218],
         ["2010-02-08",110],
         ["2010-02-15",189],
         ["2010-02-22",181],
         ["2010-03-01",300],
         ["2010-03-08",197],
         ["2010-03-15",328],
         ["2010-03-22",227],
         ["2010-03-29",395],
         ["2010-04-05",347],
         ["2010-04-12",320],
         ["2010-04-19",335],
         ["2010-04-26",450],
         ["2010-05-03",270],
         ["2010-05-10",1033],
         ["2010-05-17",450],
         ["2010-05-24",194]
      ],
      "unsubscribed":[
         ["2010-01-04",97],
         ["2010-01-11",100],
         ["2010-01-18",93],
         ["2010-01-25",163],
         ["2010-02-01",74],
         ["2010-02-08",58],
         ["2010-02-15",62],
         ["2010-02-22",41],
         ["2010-03-01",54],
         ["2010-03-08",57],
         ["2010-03-15",85],
         ["2010-03-22",74],
         ["2010-03-29",141],
         ["2010-04-05",65],
         ["2010-04-12",66],
         ["2010-04-19",70],
         ["2010-04-26",135],
         ["2010-05-03",56],
         ["2010-05-10",94],
         ["2010-05-17",77],
         ["2010-05-24",28]
      ],
      "bounced":[
         ["2010-01-04",193],
         ["2010-01-11",76],
         ["2010-01-18",74],
         ["2010-01-25",76],
         ["2010-02-01",897],
         ["2010-02-08",71],
         ["2010-02-15",69],
         ["2010-02-22",52],
         ["2010-03-01",144],
         ["2010-03-08",53],
         ["2010-03-15",161],
         ["2010-03-22",176],
         ["2010-03-29",249],
         ["2010-04-05",80],
         ["2010-04-12",99],
         ["2010-04-19",60],
         ["2010-04-26",279],
         ["2010-05-03",83],
         ["2010-05-10",172],
         ["2010-05-17",126],
         ["2010-05-24",54]
      ]
   }
}

Total List Aggregates

list_id

Include one or more list_id parameters to restrict the result set to one or more lists; if no list_id parameter is present, all lists will be returned.

Example Query

https://edm2.taguchimail.com/admin/api/1/stats/list?start_date=2009-06-02T00%3A00%3A00&end_date=2010-06-01T00%3A00%3A00&period=all

Example Response (JSON)

{
   "1":{
      "active":[
         ["all",3777]
      ],
      "total":[
         ["all",12267]
      ],
      "unsubscribed":[
         ["all",3209]
      ],
      "bounced":[
         ["all",5281]
      ]
   },
   "4":{
      "active":[
         ["all",9]
      ],
      "total":[
         ["all",13]
      ],
      "unsubscribed":[
         ["all",3]
      ],
      "bounced":[
         ["all",1]
      ]
   },
   "5":{
      "active":[
         ["all",2]
      ],
      "total":[
         ["all",2]
      ],
      "unsubscribed":[
         ["all",0]
      ],
      "bounced":[
         ["all",0]
      ]
   },
   "7":{
      "active":[
         ["all",-51]
      ],
      "total":[
         ["all",5]
      ],
      "unsubscribed":[
         ["all",7]
      ],
      "bounced":[
         ["all",49]
      ]
   }
}

Introduction

Authentication

Username/Password Auth

Token Auth

Error Handling

Format Settings

Queries

sort

order

limit

offset

query

eq

neq

lt

gt

lte

gte

re

rei

like

is

nt

Activity Resource

Operations

GET

PUT

POST

DELETE

PROOF

list_id

subscriber_id

revision_id

protocol

server

format

tag

message

APPROVAL

list_id

revision_id

protocol

server

format

tag

message

COMMENT

message

APPROVE

message

QUEUE

TRIGGER

date

conditions

test

protocol

server

format

request_content

Common Fields

id

ref

name

type

subtype

status

target-lists

target-views

approval-status

date

throttle

data

organization

campaign

template

Revisions

id

content

template-revision

combinations

`sort`

`order`

`limit`

`offset`

`query`

`eq`

`neq`

`lt`

`gt`

`lte`

`gte`

`re`

`rei`

`like`

`is`

`nt`

`GET`

`PUT`

`POST`

`DELETE`

`PROOF`

`list_id`

`subscriber_id`

`revision_id`

`protocol`

`server`

`format`

`tag`

`message`

`APPROVAL`

`list_id`

`revision_id`

`protocol`

`server`

`format`

`tag`

`message`

`COMMENT`

`message`

`APPROVE`

`message`

`QUEUE`

`TRIGGER`

`date`

`conditions`

`test`

`protocol`

`server`

`format`

`request_content`

`id`

`ref`

`name`

`type`

`subtype`

`status`

`target-lists`

`target-views`

`approval-status`

`date`

`throttle`

`data`

`organization`

`campaign`

`template`

`id`

`content`

`template-revision`

`combinations`

`approval-status`

`timestamp`

`GET`

`PUT`

`POST`

`DELETE`

`id`

`ref`

`name`

`date`

`success-event`