XML Response Document

JREllis
Published on March 6, 2017 / Updated on August 2, 2019

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

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"

JoanGriffin June 06, 2017

Thanks for fixing the links.

Reply

XML Response Document

How it works

Error Codes

Error Codes in XML Response Documents

Notification Only

Errors Requiring Action

Transact XML Response Document schema

Response Document schema Rev 1.3

XML Response Element Definitions

General Submission Response and Error Elements

Recipient and Content Elements

Join The Discussion Cancel reply