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.
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
- 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.
- Campaign ID is missing
- Campaign ID is not numeric
- CampaignID + parsedCampaignID + not numeric
- CampaignID + CampaignID + not found
- 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).
- You do not have permission to access Transact from your IP address, or you have added this IP
- 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
- 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:
|
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> |
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> |
Thanks for fixing the links.