XML Response Document

XML Response Document

After an XML submission, the server returns an XML Response
Document. The response is an assurance of receipt and of sending to the contact, or it reports a non-delivery and the reason.

How it works

The response is sent either as a string returned from the HTTP request, or delivered to the status directory of the submitter’s FTP site if the submission is sent by using FTP.

Note: The Delivery confirmation option (contact receipt acknowledgment) of the email is set in the interface and is sent to the email address specified in administrative settings.

The response identifies the group of automated messages, transaction, number of contacts, error, status, and contact information.

Error Codes

sample_response_document.png

Error Codes in XML Response Documents

You might receive the following types of errors in a Response Document following a
Transact XML submission.

Notification Only

Name Description
SAVE_COLUMN_NOT_IN_DATABASE_WARNING = 7 This is not an error, just a warning; one or more save columns that are not found in the database.
SAVE_COLUMN_TOO_LONG = 8 This is not an error, just a warning.
WARNING: COLUMN: BODY Body was too long to save with contact (maximum characters: 255)
SUPPRESSED_EMAIL = 10 Email address that is suppressed at the system or organization level.

Errors Requiring Action

GENERAL_ERROR = 1

This is due to server error (likely an exception, such as those shown below).

Exception: javax.xml.bind.UnmarshalException: The entity name must immediately follow
the Ampersand character (&) in the entity reference.

Caused by lacking CDATA tags around a value that includes an ampersand, or (if you are passing
the XML as part of the query string) it can indicate that you need to URL-encode the XML portion of the URL.

Exception:javax.xml.bind.UnmarshalException: Unexpected element {}:XXXXX

You are missing the slash symbol ( / ) in the closing tag (for example, </XXXXX>) of one of
your elements, which is specified in the XXXXX area of the error.

Exception:javax.xml.bind.UnmarshalException: The element type “XXXXX” must be
terminated by the matching end-tag “</XXXXX>”.

The spelling of the closing tag for the specified element is different than its opening counterpart.

Exception:javax.xml.bind.UnmarshalException: XML document structures must start and end within the same entity.

  • One of your XML declarations is missing its closing quotation.
    • Incorrect: <?xml version=”1.0?>
    • Correct: <?xml version=”1.0″?>
  • You are missing a bracket in the closing CDATA tag.

Exception:javax.xml.bind.UnmarshalException: Element type “XXXXX” must be followed by
either attribute specifications, “>” or “/>”.

There is a less-than symbol ( < ) not enclosed in CDATA tags within one of your elements, or that was not added following greater-than ( > ) symbol.

Exception:javax.xml.bind.UnmarshalException: a pseudo attribute name is expected.

The trailing question mark in the XML declaration string is missing:

<?xml version=”1.0″ encoding=”UTF-8″?>

Exception:javax.xml.bind.UnmarshalException: The value following “version” in the XML
declaration must be a quoted string.

There must be quotation marks around the 1.0 in the XML declaration string, for example, <?xml
version=”1.0″ encoding=”UTF-8″?>

Exception:javax.xml.bind.UnmarshalException: Content is not allowed in prolog.

You cannot include any content (text characters) outside of the <XTMAILING> tags

Exception:javax.xml.bind.JAXBException – with linked exception:
[java.io.UTFDataFormatException: Invalid byte # of #-byte UTF-8 sequence.]

XML has a high-bit character in it that has not been ASCII-encoded. Accented and non-ISO
characters fall into this category.

Exception:javax.xml.bind.UnmarshalException: The content of elements must consist of well-formed character data or markup.

There is likely a symbol or other issue with an element name. For example, entering the following element <$AFW></$AFW> in the XML might cause this error.

Exception:javax.xml.bind.UnmarshalException: Attribute name “XXXXX” associated with an element type “XXXXX” must be followed by the ‘ = ‘ character.

There is an extra word or character in an XML element tag that you should remove, as XML
perceives this as an attribute of the element.

Exception:javax.xml.bind.UnmarshalException: Expecting an opening quotation mark for attribute “XXXXX” associated with an element type “XXXXX”.

An attribute has been associated with one of your XML elements that was not enclosed in quotation marks. For example, <element attribute=value”>. You should remove the attribute and value from the Element tag.

PARSING_ERROR = 2

The document didn’t parse. The message will often provide more information about the issue.

INVALID_DATA_ERROR = 4

CampaignID ###### not found. Occurs when:

  • Running against an Automated Message ID that doesn’t exist in your organization.
  • The Group has not had time to synchronize (requires approximately 10 minutes).
  • The Group has no mailing automation.
  • There is a non-numeric character in the Campaign ID element.
For a request (return error string):

  • Campaign ID is missing
  • Campaign ID is not numeric
  • CampaignID + parsedCampaignID + not numeric
  • CampaignID + CampaignID + not found
For an individual contact (return error string):

  • Missing email
  • Missing tag name
  • Missing value
  • Invalid email address + emailAddress
  • Invalid body type ” + bodyType

ACCESS_ERROR = 5

  • Access is not allowed to application for this IP ###.###.###.###
    • You do not have permission to access Transact from your IP address, or you have added this IP
      address to your Security Settings (within Org Admin), but it has not had time to synchronize with
      Transact (requires approximately 10 minutes).
  • Access not allowed to application for this IP + IPAddress
    • Access is not allowed to this group mailing for this IP + IPAddress

SETUP_ERROR = 9

  • No VMTA found for this Group
    • Contact Support for assistance in correcting this problem.

Each error message also contains a STATUS indicator that provides additional information
regarding whether the email sent to your intended contact.

STATUS Values

0 – no errors are encountered during the send; all contacts sent.

1 – encountered errors during the send; some or all contacts were not sent

2 – encountered errors with the XML submission; no contacts were sent; no contact error details
are provided; only the request-level error.

SEND_STATUS Values

0 – no errors are encountered during the send.

1 – error are encountered during the send, send will not be retried.

2 – request received; send cached for later send.

Transact XML Response Document schema

We provide the following schemas for Transact for illustrative purposes only. We do not recommend copying schemas and using them for XML validation in a production environment without thorough testing.

Response Document schema Rev 1.3

<xsd:element name='XTMAILING_RESPONSE'>
<xsd:complexType>
<xsd:sequence>
<xsd:element name='CAMPAIGN_ID' type='xsd:string' minOccurs='0'/>
<xsd:element name='TRANSACTION_ID' type='xsd:string' minOccurs='0'/>
<xsd:element name='RECIPIENTS_RECEIVED' type='xsd:unsignedLong' default='0'/>
<xsd:element name='EMAILS_SENT' type='xsd:unsignedLong' default='0'/>
<xsd:element name='NUMBER_ERRORS' type='xsd:unsignedLong' default='0'/>
<xsd:element name='STATUS' type='xsd:unsignedInt'/>
<xsd:element name='ERROR_CODE' type='xsd:unsignedInt'/>
<xsd:element name='ERROR_STRING' type='xsd:string'/>
<xsd:element name='RECIPIENT_DETAIL' minOccurs='0' maxOccurs='unbounded'>
<xsd:complexType>
<xsd:sequence>
<xsd:element name='EMAIL' type='xsd:string' minOccurs='0'/>
<xsd:element name='SEND_STATUS' type='xsd:unsignedInt'/>
<xsd:element name='ERROR_CODE' type='xsd:unsignedInt'/>
<xsd:element name='ERROR_STRING' type='xsd:string'/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

XML Response Element Definitions

This article contains definitions about General Submission Response and Error Elements and Recipient and Content Elements.

General Submission Response and Error Elements

For information on Derived data types, see: W3C XML Schema Part 2: Datatypes Second Edition.

This section contains these elements and their definitions:

  • XTMAILING_RESPONSE
  • CAMPAIGN_ID
  • TRANSACTION_ID
  • RECIPIENTS_RECEIVED
  • EMAILS_SENT
  • NUMBER_ERRORS
  • STATUS
  • ERROR_CODE
  • ERROR_STRING
Element: XTMAILING_RESPONSE Usage: Required Sequence: Top-level
Description: Top-level element encapsulating the XML document
that provides the response information for the generated and sent emails.
Element type: Complex Data type: N/A Default Value: N/A Limit: N/A
Values: None
Occurrence indicators None
Attributes None
Note: N/A
Example:
<XTMAILING_RESPONSE>Elements</XTMAILING_RESPONSE>
Element: CAMPAIGN_ID Usage: Required Sequence: after XTMAILING_RESPONSE
Description: Transact uses the Campaign ID to map the content to the Group of Automated Messages.
Element type: Complex Data type: string Default Value: N/A Limit: 255 characters
Values: Number of the Group that is used for the mailing, which must be a valid ID number that is assigned to the user.
Occurrence indicators None
Attributes

minOccurs=”1″

Values:

1 = at least one of them is required.

Note: None
Example:
<CAMPAIGN_ID>300401</CAMPAIGN_ID>
Element: TRANSACTION_ID Usage: Optional Sequence: after CAMPAIGN_ID
Description: Optional parameter that is used by the sender for uniquely identifying a transaction. The Response Document returns the value specified if used in the original request.
Element type: Complex Datatype: string Default Value: N/A Limit: 255 characters
Values: Transaction ID number to be used for the mailing (can be any valid Transaction ID number that is assigned by the user).
Occurrence indicators

minOccurs=”0″

Values:

0 = element is optional

Attributes None
Note: None
Example:
<TRANSACTION_ID>TRANS-1234</TRANSACTION_ID>
Element: RECIPIENTS_
RECEIVED
Usage: Required Sequence: after TRANSACTION_ID
Description: Number of recipients that are processed in the submission.
Element type: Complex Data type: unsignedLong Default Value: 0 Limit: N/A

Values:

1…n = Number of recipient addresses received.

Occurrence indicators None
Attributes None
Note: None
Example:
<RECIPIENTS_RECEIVED>1</RECIPIENTS_RECEIVED>
Element: EMAILS_SENT Usage: Required Sequence: after RECIPIENTS_RECEIVED
Description: Number of emails that are sent from the submission.
Element type: Complex Data type: unsignedLong Default Value: 0 Limit: N/A

Values:

1…n = Number of emails sent.

Occurrence indicators None
Attributes None
Notes: None
Example:
<EMAILS_SENT>0</EMAILS_SENT>
Element: NUMBER_ERRORS Usage: Required Sequence: after EMAILS_SENT
Description: The number of errors that are generated when processing the submission.
Element type: Complex Data type: unsignedLong Default Value: 0 Limit: N/A

Values:

1…n = Number of errors.

Occurrence indicators None
Attributes None
Notes: None
Example: <NUMBER_ERRORS>1</NUMBER_ERRORS>
Element: STATUS Usage: Required Sequence: after NUMBER_ERRORS
Description: The description of errors that are generated when processing the submission.
Element type: Complex Data type: unsignedInt Default Value: N/A Limit: N/A

Values:

0 – Did not encounter any errors during the send; all recipients sent.

1 – Encountered errors during the send; some or all recipients were not sent

2 – Encountered errors with the XML submission; no recipients were sent; no recipient error details are provided, only the request-level error.

Occurrence indicators None
Attributes: None
Note: None
Example: <STATUS>2</STATUS>
Element: ERROR_CODE Usage: Required Sequence: after STATUS
Description: Detailed description of errors that are generated
when processing the submission.
Element type: Complex Data type: unsignedInt Default Value: N/A Limit: N/A
Values: 1 n = Number identifying error code.
Occurrence indicators None
Attributes None
Note: None

Example:

<ERROR_CODE>0</ERROR_CODE>

Element: ERROR_STRING Usage: Required Sequence: after ERROR_CODE
Description: Error message.
Element type: Complex Data type: string Default Value: N/A Limit: 255 characters
Values: Error message sent.
Occurrence indicators None
Attributes None
Note: None

Example:

<ERROR_STRING>Campaign ID is missing</ERROR_STRING>

Recipient and Content Elements

This section contains these elements and their definitions:

  • RECIPIENT_DETAIL
  • EMAIL
  • SEND_STATUS
  • ERROR_CODE
  • ERROR_STRING
Element: RECIPIENT_DETAIL Usage: Required Sequence: Top-level
Description: Multiple occurrences possible. One for each recipient.
Element type: Complex, Elements Data type: string Default Value: N/A Limit: 255 characters
Values: Error message text.
Occurrence indicators

minOccurs=”1″

Values:

1 = at least one of them is required.

maxOccurs=”unbounded”

Values:

unbounded= (no limit)

Attributes None
Note: None

Example:

<RECIPIENT_DETAIL>
<EMAIL><EMAIL>
<SEND_STATUS><SEND_STATUS>
<ERROR_CODE><ERROR_CODE>
<ERROR_STRING><ERROR_STRING>
</RECIPIENT_DETAIL>
Element: EMAIL Usage: Required Sequence: after RECIPIENT_DETAIL
Description: Contains the email address to which the transactional email was sent (recipient).
Element type: Complex Data type: string Default Value: N/A Limit: 255 characters
Values: Address text
Occurrence indicators

minOccurs=”1″

Values:

1 = at least one of them is required.

Attributes None
Note: None
Example:
<EMAIL>person@domain.com</EMAIL>
Element: SEND_STATUS Usage: Required Sequence: after EMAIL
Description: Status of the send to the recipient.
Element type: Complex Data type: unsignedInt Default Value: N/A Limit: N/A

Values:

0 – no errors that are encountered during the send.

1 – Encountered an error during the send, will not retry the send.

2 – request received; send cached for later send.

Occurrence indicators None
Attributes None
Note: None
Example:
<SEND_STATUS>1</SEND_STATUS>
Element: ERROR_CODE Usage: Required Sequence: after SEND_STATUS
Description: Error code that is generated for the specific recipient.
Element type: Complex Data type: unsignedInt Default Value: N/A Limit: N/A
Values: 1 n = Number identifying THE error code.
Occurrence indicators None
Attributes None
Note: None

Example:

<ERROR_CODE>4</ERROR_CODE>

See: Error Codes in XML Response Documents

Element: ERROR_STRING Usage: Required Sequence: after ERROR_CODE
Description: Error message that is generated for the specific recipient.
Element type: Complex Data type: string Default Value: N/A Limit: 255 characters
Values: Error message text.
Occurrence indicators None
Attributes None
Note: None

Example:

<ERROR_STRING>Campaign ID is missing</ERROR_STRING>

See: Error Codes in XML Response Documents

1 comment on"XML Response Document"

  1. JoanGriffin June 06, 2017

    Thanks for fixing the links.

Join The Discussion

Your email address will not be published. Required fields are marked *