6. Mailing
Content of this chapter
This chapter contains web service methods concerning the mailing creation.
6.1. AddMailing
Namespace: http://agnitas.org/ws/schemas
Creates a new mailing without content and with no template used.
'targetIDList', 'senderName' and 'replyToName' fields are optional.
6.1.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| shortname | {http://www.w3.org/2001/XMLSchema}string | short name of a mailing to be inserted |
| description | {http://www.w3.org/2001/XMLSchema}string | description of a mailing to be inserted |
| mailinglistID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing list for the mailing |
| targetIDList | {http://www.w3.org/2001/XMLSchema}element | list of target group's ID to form target expression |
| matchTargetGroups | {http://www.w3.org/2001/XMLSchema}string | defines whether to match one or all of the target groups, allowed values ‘all’ and ‘one’ |
| mailingType | {http://www.w3.org/2001/XMLSchema}string | type of mailing, 'regular', 'action-based', 'rule-based' |
| subject | {http://www.w3.org/2001/XMLSchema}string | the subject of a mailing |
| senderName | {http://www.w3.org/2001/XMLSchema}string | appears as a full name of the sender |
| senderAddress | {http://www.w3.org/2001/XMLSchema}string | the address shown as sender of the e-mail |
| replyToName | {http://www.w3.org/2001/XMLSchema}string | a full name of an institution or person to send response to |
| replyToAddress | {http://www.w3.org/2001/XMLSchema}string | the address for responses |
| charset | {http://www.w3.org/2001/XMLSchema}string | charset to use in email |
| linefeed | {http://www.w3.org/2001/XMLSchema}int | interval at which line break symbols are put in text mailing |
| format | {http://www.w3.org/2001/XMLSchema}string | format of a mailing - 'text', 'Online-HTML' or 'OfflineHTML' |
| onePixel | {http://www.w3.org/2001/XMLSchema}string | defines position where a tracking pixel is inserted |
| plannedDate | {http://www.w3.org/2001/XMLSchema}dateTime | optional planned date in ISO8601 format |
Optional elements:
| Elements | Default behavior, if not specified |
|---|---|
| description | Description is empty |
| senderName | Name is empty |
| replyToName | Name is empty |
| plannedDate | Date not set |
6.1.2. Response elements
| Element | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of an inserted mailing |
6.1.3. SOAP Faults
A SOAP fault is returned, if
- a mandatory field is missing,
- one of the given IDs is not positive,
- the format of the email address is not valid or
- the values of the elements "matchTargetGroups", "mailingType", "format" and "onePixel" are not in allowed range.
6.2. AddMailingFromTemplate
Namespace: http://agnitas.org/ws/schemas
Creates a new mailing from a template.
6.2.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| templateID | {http://www.w3.org/2001/XMLSchema}int | ID of template used to create mailing |
| shortname | {http://www.w3.org/2001/XMLSchema}string | short name of a mailing to be inserted |
| description | {http://www.w3.org/2001/XMLSchema}string | description of a mailing to be inserted |
| autoUpdate | {http://www.w3.org/2001/XMLSchema}boolean | When set to "true" any successive changes in the content blocks of the template will be overtaken for the mailing, too. |
| plannedDate | {http://www.w3.org/2001/XMLSchema}dateTime | optional planned date in ISO8601 format |
Optional elements:
| Element | Default behavior, if not specified |
|---|---|
| description | Description of mailing is empty |
| plannedDate | Date not set |
6.2.2. Response elements
| Element | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of an inserted mailing |
6.2.3. SOAP Faults
A SOAP fault is returned, when there is no template with the given ID, any of the mandatory request fields is missing or any of identifiers is not positive.
6.3. GetMailing
Namespace: http://agnitas.org/ws/schemas
Retrieves a mailing by ID.
6.3.1. Request elements
| Element | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing in question |
6.3.2. Response elements
| Elements | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing in question |
| shortname | {http://www.w3.org/2001/XMLSchema}string | short name of a mailing |
| description | {http://www.w3.org/2001/XMLSchema}string | description of a mailing |
| mailinglistID | {http://www.w3.org/2001/XMLSchema}int | mailing list for the mailing |
| targetIDList | {http://www.w3.org/2001/XMLSchema}element | list of target groups ID's to form target expression |
| matchTargetGroups | {http://www.w3.org/2001/XMLSchema}string | defines whether to match one or all of the target groups, allowed values ‘all’ and ‘one’ |
| mailingType | {http://www.w3.org/2001/XMLSchema}string | type of mailing, 'regular', 'action-based', 'rule-based' |
| subject | {http://www.w3.org/2001/XMLSchema}string | the subject of a mailing |
| senderName | {http://www.w3.org/2001/XMLSchema}string | appears as a full name of the sender |
| senderAddress | {http://www.w3.org/2001/XMLSchema}string | the address shown as sender of the e-mail |
| replyToName | {http://www.w3.org/2001/XMLSchema}string | a full name of an institution or person to send response to |
| replyToAddress | {http://www.w3.org/2001/XMLSchema}string | the address for responses |
| charset | {http://www.w3.org/2001/XMLSchema}string | charset to use in email |
| linefeed | {http://www.w3.org/2001/XMLSchema}int | interval at which line break symbols are put in text mailing |
| formats | {http://www.w3.org/2001/XMLSchema}element | formats a mailing can sent in |
| onePixel | {http://www.w3.org/2001/XMLSchema}string | defines position where a tracking pixel is inserted |
| autoUpdate | {http://www.w3.org/2001/XMLSchema}boolean | mailing list for the mailing |
| plannedDate | {http://www.w3.org/2001/XMLSchema}dateTime | planned date in ISO8601 format |
6.3.3. SOAP Faults
A SOAP fault is returned, if the mailingID request field is missing, it is not a positive value, or there is no mailing with the given ID.
6.4. ListMailings
Namespace: http://agnitas.org/ws/schemas
Retrieves a list of all mailings.
6.4.1. Request elements
| Element | Data type | Description |
|---|---|---|
| filter | Optional element with filter settings |
Subelement of "filter":
| Element | Data type | Description |
|---|---|---|
| mailingStatus | {http://www.w3.org/2001/XMLSchema}string | Optional element for mailing status. Possible values can be found in section A.10 Mailing status values. Cannot be used together with "mailingStatusList". |
| mailingStatusList | List of "mailingStatus" elements | Optional element for list of mailing states. Possible values can be found in section A.10 Mailing status values. Cannot be used together with "mailingStatus". |
| sentBefore | Optional element for send time of mailing. Checks, that mailing has been sent before given time stamp. | |
| sentAfter | Optional element for send time of mailing. Checks, that mailing has been sent after given time stamp. |
Subelements of "sentBefore" and "sentAfter":
| Element | Data type | Description |
|---|---|---|
| timestamp | {http://www.w3.org/2001/XMLSchema}dateTime | Send time |
| inclusive | {http://www.w3.org/2001/XMLSchema}boolean | Optional element to set if timestamp is included |
For date format of timestamp see Date format.
Optional elements:
| Element | Default behavior, if not specified |
|---|---|
| filter | All mailings of account will be listed |
| inclusive | For "sentAfter": Time stamp is inclusive For "sentBefore": Time stamp is exklusive |
6.4.2. Response elements
| Element | Data type | Description |
|---|---|---|
| item | {http://agnitas.org/ws/schemas}Mailing | list of mailings, empty if there are no mailings |
6.4.3. SOAP faults
The webservice returns a SOAP fault when
- an invalid mailing status is given
- "mailingStatus" and "mailingStatusList" are used together
6.5. ListMailingsInMailinglist
Namespace: http://agnitas.org/ws/schemas
Retrieves a list of mailings for a particular mailing list.
6.5.1. Request elements
| Element | Data type | Description |
|---|---|---|
| mailinglistID | {http://www.w3.org/2001/XMLSchema}int | ID of an mailing list |
6.5.2. Response elements
| Element | Data type | Description |
|---|---|---|
| item | {http://agnitas.org/ws/schemas}Mailing | list of mailings, empty if there are no mailings |
6.5.3. SOAP Faults
A SOAP fault is returned, if the mailinglistID request field is missing, it is not a positive value, or there is no mailing list with the given ID.
6.6. UpdateMailing
Namespace: http://agnitas.org/ws/schemas
Updates a mailing with the given ID. If there is no such mailing a SOAP fault is returned.
6.6.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing in question |
| shortname | {http://www.w3.org/2001/XMLSchema}string | short name of a mailing to be updated |
| description | {http://www.w3.org/2001/XMLSchema}string | description of a mailing to be updated |
| mailinglistID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing list for the mailing |
| targetIDList | {http://www.w3.org/2001/XMLSchema}element | list of target group's ID to form target expression |
| matchTargetGroups | {http://www.w3.org/2001/XMLSchema}string | defines whether to match one or all of the target groups, allowed values ‘all’ and ‘one’ |
| mailingType | {http://www.w3.org/2001/XMLSchema}string | type of mailing, 'regular', 'action-based', 'rule-based' |
| subject | {http://www.w3.org/2001/XMLSchema}string | the subject of a mailing |
| senderName | {http://www.w3.org/2001/XMLSchema}string | appears as a full name of the sender |
| senderAddress | {http://www.w3.org/2001/XMLSchema}string | the address shown as sender of the e-mail |
| replyToName | {http://www.w3.org/2001/XMLSchema}string | a full name of an institution or person to send response to |
| replyToAddress | {http://www.w3.org/2001/XMLSchema}string | the address for responses |
| charset | {http://www.w3.org/2001/XMLSchema}string | charset to use in email |
| linefeed | {http://www.w3.org/2001/XMLSchema}int | interval at which line break symbols are put in text mailing |
| format | {http://www.w3.org/2001/XMLSchema}string | format of a mailing - 'text', 'Online-HTML' or 'OfflineHTML' |
| onePixel | {http://www.w3.org/2001/XMLSchema}string | defines position where a tracking pixel is inserted |
| plannedDate | {http://www.w3.org/2001/XMLSchema}dateTime | optional planned date in ISO8601 format |
Optional elements:
| Elements | Default behavior, if not specified |
|---|---|
| description | Description becomes empty |
| senderName | Name becomes empty |
| replyToName | Name becomes empty |
| plannedDate | Date not set |
6.6.2. Response elements
Note: The response has no elements.
6.6.3. SOAP Faults
A SOAP fault is returned, if any of the mandatory request fields is missing, any of identifiers is not positive, the format of the email address is invalid, values of 'matchTargetGroups', 'mailingType', 'format' or 'onePixel' do not belong to correspondent designated ranges.
6.7. DeleteMailing
Namespace: http://agnitas.org/ws/schemas
Deletes a mailing with the given ID.
6.7.1. Request elements
| Element | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing in question |
6.7.2. Response elements
Note: The response has no elements.
6.7.3. SOAP Faults
A SOAP fault is returned, if a mailing with the given ID does not exist.
6.8. GetMailingContent
Namespace: http://agnitas.com/ws/schemas
Returns the frame content of a mailing. This content can also be viewed and modified for a mailing in the web user interface in the tab “Mailing” section “Template”.
6.8.1. Request elements
| Element | Data type | Description |
|---|---|---|
| mailingId | {http://www.w3.org/2001/XMLSchema}int | ID des Mailings |
6.8.2. Response elements
| Element | Data type | Description |
|---|---|---|
| items | List of elements of type {http://agnitas.com/ws/schemas}MailingContent | List of content |
The elements of type {http://agnitas.com/ws/schemas}MailingContent have the following structure:
| Elements | Data type | Description |
|---|---|---|
| name | {http://www.w3.org/2001/XMLSchema}string | Name of content |
| content | {http://www.w3.org/2001/XMLSchema}string | content |
The contents can have the following name:
- agnText for plain text mailings,
- agnHtml for mailing with HTML content
6.8.3. SOAP Faults
The server returns Soap Faults if the mailing ID is unknown, the mailing is deleted or the mailing ID does not belong to the account of the web service user.
6.9. UpdateMailingContent
Namespace: http://agnitas.org/ws/schemas
Updates the frame content of a mailing. This content can also be viewed and modified for a mailing in the web user interface in the tab “Mailing” section “Template”.
6.9.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of mailing to update the frame content |
| componentName | {http://www.w3.org/2001/XMLSchema}string | Name of the frame content |
| newContent | {http://www.w3.org/2001/XMLSchema}string | New content |
6.9.2. Response elements
Note: The response has no elements.
6.9.3. SOAP Faults
In case of an error a Soap Fault is returned.
6.10. SendMailing
Namespace: http://agnitas.org/ws/schemas
Sends a mailing. 'blocksize', 'stepping' and 'doubleCheck' fields are optional.
6.10.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing to send |
| recipientsType | {http://www.w3.org/2001/XMLSchema}string | types of recipients a mailing is being sent to: administrators, test recipients or regular recipients (allowed: admin, test, world) |
| sendDate | {http://www.w3.org/2001/XMLSchema}dateTime | date when sending process should start |
| blocksize | {http://www.w3.org/2001/XMLSchema}int | tunes sending process speed |
| stepping | {http://www.w3.org/2001/XMLSchema}int | tunes sending process speed |
| doubleCheck | {http://www.w3.org/2001/XMLSchema}boolean | If set to true, check for duplicate recipients is performed before sending |
Optional elements:
| Elements | Default behavior, if not specified |
|---|---|
| blocksize | Uses value 0. |
| stepping | Uses value 0. |
| doubleCheck | false, no check for duplicate recipients |
Format for send date see " Date format ".
6.10.2. Response elements
Note: The response has no elements.
6.10.3. SOAP Faults
A SOAP fault is returned, if any of the mandatory request fields is missing, if mailing ID, blocksize and stepping are not positive values, recipientsType is not a proper recipient type (admin, test or world) or sendDate is not in the future.
6.11. SendServiceMail
Namespace: http://agnitas.org/ws/schemas
This web service triggers an EMM action, which sends a service mail. The mail is sent to the email address that is specified in the EMM action.
6.11.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| actionID | {http://www.w3.org/2001/XMLSchema}int | ID of EMM action that send the service mail |
| customerID | {http://www.w3.org/2001/XMLSchema}int | ID of subscriber that triggered the service mail |
6.11.2. Response elements
In case of successful execution, the web service returns a empty response with no elements.
6.11.3. SOAP Faults
A SOAP fault is returned in case of an error (unknown action ID, unknown subscriber ID, error during sending the email, ....).
6.12. GetMailingStatus
Namespace: http://agnitas.org/ws/schemas
Returns the work status of a mailing.
6.12.1. Request elements
| Element | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | Mailing ID |
6.12.2. Response elements
| Element | Data type | Description |
|---|---|---|
| status | {http://www.w3.org/2001/XMLSchema}string | Work status of mailing |
Possible values for the mailing status can be found in section A.10 Mailing status values.
6.12.3. SOAP Faults
The server returns a SOAP Fault if given mailing ID is unknown.
6.13. DeactivateMailing
Namespace: http://agnitas.org/ws/schemas
Deactivates an active Mailing.
6.13.1. Request elements
| Element | Data type | Description |
|---|---|---|
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of a mailing to deactivate |
6.13.2. Response elements
In case of successful execution, the web service returns a empty response with no elements.
6.13.3. SOAP Faults
The server returns a SOAP Fault if given mailing ID is unknown.
6.14. CopyMailing
Namespace: http://agnitas.org/ws/schemas
Copies an existing mailing.
6.14.1. Request elements
| Elements | Data type | Description |
|---|---|---|
| mailingId | {http://www.w3.org/2001/XMLSchema}int | ID of mailing to be copied |
| nameOfCopy | {http://www.w3.org/2001/XMLSchema}string | Name of copy |
| descriptionOfCopy | {http://www.w3.org/2001/XMLSchema}string | Description of copy |
Optional elements:
| Element | Default behavior, if not specified |
|---|---|
| descriptionOfCopy | Description of original mailing is used |
6.14.2. Response elements
| Element | Data type | Description |
|---|---|---|
| copyId | {http://www.w3.org/2001/XMLSchema}int | Mailing ID of copy |
6.14.3. SOAP Faults
If required elements are missing or the given mailing ID is unknown a SOAPFault is returned.
6.15. ListSubscriberMailings
Namespace: http://agnitas.org/ws/schemas
Lists all mailings sent to given recipient.
6.15.1. Request elements
| Elemente | Datentyp | Beschreibung |
|---|---|---|
| customerID | {http://www.w3.org/2001/XMLSchema}int | ID of recipient |
6.15.2. Response elements
| Elements | Data types | Description |
|---|---|---|
| items | List of {http://agnitas.org/ws/schemas}Map | Information on received mailings |
Each item of the list contains these information:
| Key | Description |
|---|---|
| mailing_id | ID of mailing |
| senddate | Date when the mailing was send |
| mailing_type | Type of mailing (see A.3 Values for MAILTYPE ) |
| mailing_name | Name of mailing |
| mailing_subject | Subject |
| openings | Number of openings |
| clicks | Number of clicks |
6.15.3. SOAP Faults
Ein SOAP Fault wird geliefert, wenn die angegebene Empfänger-ID unbekannt ist.
6.16. GetFullviewUrl
Namespace: http://agnitas.com/ws/schemas
Returns the URL of a fullview of a mailing for a specific recipent. The fullview URL is based on the usage of a fullview form.
6.16.1. Request elements
| Elemente | Datentyp | Beschreibung |
|---|---|---|
| customerID | {http://www.w3.org/2001/XMLSchema}int | ID of the recipient |
| mailingID | {http://www.w3.org/2001/XMLSchema}int | ID of the mailing |
| formName | {http://www.w3.org/2001/XMLSchema}string | Name of fullview form |
Optional elements:
| Element | Default behavior, if not specified |
|---|---|
| formName | The default name "fullview" or another configure default name is used |
6.16.2. Response elements
| Elemente | Datentyp | Beschreibung |
|---|---|---|
| url | {http://www.w3.org/2001/XMLSchema}string | URL to fullview |
6.16.3. SOAP Faults
GetFullviewUrl returns a SOAP fault if
- mailing ID is unknown
- recipient ID is unknown
- specified fullview form does not exist