Integration Guide Xura Messaging SMTP- Interface

Transcription

1 Integration Guide Xura Messaging SMTP- Interface Version Content is subject to change Xura Secure Communications GmbH Tel.: : asc-support@xura.com All rights reserved. This product and related documentation are protected by copyright and under licenses restricting its use, copying, distribution and compilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorisation of Xura Secure Communications GmbH.

2 TABLE OF CONTENTS 1 REVISION HISTORY INTRODUCTION Setup and Connection Data Authentication Validity checks Rejects Delivery Notifications Splitting of Overlong Messages SMTP INTERFACE DESCRIPTION SMTP Outbound Parameters EXAMPLES Simple case - using only the mandatory parameter Composed message as plain source text Authentication via CID Composed message as plain source text (CID in subject) message as plain source text (CID in header) Sample with all parameters set Composed message as plain source text Request acknowledge notification via RFC SMTP protocol Acknowledge Notification example Request disposition notifications via RFC Composed message as plain source text Notification example (success) Notification example (error) Page: 2 of 13

3 1 REVISION HISTORY Date Author Version Comment Benjamin Lux First version Benjamin Lux Added notification support Benjamin Lux Updated new notification config Benjamin Lux Added Validity period Table 1: Revision History Page: 3 of 13

4 2 INTRODUCTION The Xura Secure Communications GmbH provides a secure and highly available platform. It offers different messaging interfaces for sending and receiving messages. This document describes the Xura SMTP-Interface and provides various examples. The Xura SMTP-Interface offers an easy way to send a SMS message via to a mobile phone. This is done by sending an with specific parameters to a provided Xura domain. 2.1 Setup and Connection Data The SMTP interface supports sending of messages via (SMTP protocol) to the Xura Mailserver. The could be either send as Plain SMTP or encrypted via SMTPS or TLS. Xura provides customers the domain and a customer identification number (CID). 2.2 Authentication Due to security reasons Xura uses an IP-address white-list. Each customer must provide their IPaddress to apply for a Xura SMTP interface account. It will be only possible to send s from IPaddresses on this whitelist. Depending on the customers setup, the authentication via CID can be added. The default setup does not require an authentication via CID. There are two possibilities to authenticate via CID. First, the CID can be set in the subject, second the CID can be provided in the X-MM-CID header field. 2.3 Validity checks The SMTP interface validates each incoming by the following checks: an can only have one receipient (MSISDN) the parameters in the subject are validated against the parameter list in chapter 3.1 the content type of the must be text/plain if the is a multipart message, the first content with type text/plain will be chosen as SMS message text. the SMS message text must not be blank the charset of the body is set by the customer in the header and will be converted into a GSM 7-Bit message (recommended charsets are ISO or UTF8 ) upon request, the message text can be also encoded as an UCS2 message (e.g. for chinese letters). In this case, one message part may contain up to 70 chars IP address must be on the white-list in case of a prepaid SMS account, the will not be sent if the prepaid amout is empty Rejects If a validity check fails, the will be either rejected by the Xura Mailserver (e.g. IP address not on white-list) or a Bounce Message will be sent (e.g. MSISDN invalid). Page: 4 of 13

5 2.4 Delivery Notifications The SMTP interface supports two different kinds of delivery notifications (DLN). These notifications can be requested by setting the appropriate header fields in the (see the RFC s for further details): Acknowledge status notification - RFC 3461 Contains the acknowledgement, that the message was received and processed by the Xura Mail- Server. This notification will be issued to the sender address of the . In chapter 4.4 you can find an example for the acknowledge status notification. Message disposition notification - RFC 3798 (former RFC 2298) After sending the SMS to the recipient, Xura will issue this notification that the SMS was successfully sent to the mobile phone. This notification will be sent to the address specified in the Disposition-Notification-To header. Other receipients could be added by MindMaitcs upon request. In chapter 4.5 you can find examples for the message disposition notification. Furthermore it is possible to request the Message disposition notification by setting the notification parameter in the subject (see chapter 3.1). In this case the notification will be sent to the sender address. 2.5 Splitting of Overlong Messages Xura follows the GSM specifications for setting maximum message length. However, the actual delivery is dependent on the operator and the mobile phone involved. Longer messages will be sent with an internal sequence number. Normally, blocks of 153 characters are sent in the case of an ASCII message with more than 160 characters. Per default, the number of message parts is limited to 5. This value can be changed to values between 1 and 10. SMS messages which extends the maximum number of message parts will be cut after the maximum configured number of message parts and delivered. Page: 5 of 13

6 3 SMTP INTERFACE DESCRIPTION 3.1 SMTP Outbound Parameters The outbound parameters can be set in the subject field of the . Each parameter must be separated by & and the value will be set after =. If the customer wants to use a delimiter character ( & or = ) inside the subject, it must be marked with the escape character \ (backslash). The backslash is escaped by another backslash ( \\ ). e.g. from=abc\&123&myid=def\=\\ will be parsed to from=abc&123 and myid=def=\ Parameter Type Description Example from m Originating numeric telephone number (with complete country code so that replies are possible, max. 20 characters). or Alphanumeric sender max. 11 characters or Short code Xura cid o Customer identification, numeric value myid o Alphanumeric ID that can be set by customers (max. 128 characters) jobid o Numeric ID that can be set by customers. Range from 0 to notification o Indicates if a delivery notification is requested according to RFC : Delivery Notification Off (Default if not set) 1: Delivery Notification On validitytime o The maximum validity time of the message in minutes. If the recipient device is not available and the validity time is reached, the message will not be sent to the MSISDN. Table 2: SMTP Outbound Parameter Definition Default is seven days ( min) ID Page: 6 of 13

7 4 EXAMPLES 4.1 Simple case - using only the mandatory parameter Composed TO @<will be provided by Xura>.mindmatics.com FROM testuser@company.de SUBJECT from=xura CONTENT This is a test message message as plain source text Message-ID: < @company.de> Date: Wed, 14 May :05: From: Testuser <testuser@company.de> Content-Type: text/plain; charset=iso To: @<will be provided by Xura>.mindmatics.com Subject: from=xura This is a test message. Page: 7 of 13

8 4.2 Authentication via CID Composed TO be provided by Xura>.mindmatics.com FROM SUBJECT from=xura&cid=3512 CONTENT This is a test message with authentication via CID message as plain source text (CID in subject) Message-ID: < @company.de> Date: Wed, 14 May :05: From: Testuser <testuser@company.de> Content-Type: text/plain; charset=iso To: @<will be provided by Xura>.mindmatics.com Subject: from=xura&cid=3512 This is a test message with authentication via CID in the subject message as plain source text (CID in header) Message-ID: < @company.de> Date: Wed, 14 May :05: From: Testuser <testuser@company.de> Content-Type: text/plain; charset=iso To: @<will be provided by Xura>.mindmatics.com Subject: from=xura X-MM-CID: 3512 This is a test message with authentication via CID in the header. Page: 8 of 13

9 4.3 Sample with all parameters set Composed TO be provided by Xura>.mindmatics.com FROM SUBJECT from=xura&cid=3512&myid=abc&jobid=45678&notification=1&validitytime=60 CONTENT This is a test message with all parameters set message as plain source text Message-ID: < @company.de> Date: Wed, 14 May :05: From: Testuser <testuser@company.de> Content-Type: text/plain; charset=iso To: @<will be provided by Xura>.mindmatics.com Subject: from=xura&cid=3512&myid=abc&jobid=45678&notification=1&validitytime=60 This is a test message with all parameters set. Page: 9 of 13

10 4.4 Request acknowledge notification via RFC SMTP protocol <<< 220 mindmatics.com SMTP server here >>> EHLO mindmatics.com <<< 250-mindmatics.com <<< 250-DSN <<< 250-EXPN <<< 250 SIZE >>> MAIL RET=HDRS ENVID=ABCD1234 <<< 250 sender ok >>> RCPT NOTIFY=SUCCESS,FAILURE <<< 250 recipient ok >>> DATA <<< 354 okay, send message >>> (message goes here) >>>. <<< 250 message accepted >>> QUIT <<< 221 goodbye Acknowledge Notification example Message-Id: Date: Wed, 14 May :07: From: be provided by Xura>.mindmatics.com To: Subject: Delivery Notification (success) for be provided by Xura>.mindmatics.com MIME-Version: 1.0 Content-Type: multipart/report; report-type=delivery-status; boundary=frontier --frontier Content-type: text/plain Your message (id ABCD1234) was successfully delivered to be provided by Xura>.mindmatics.com --frontier Content-type: message/delivery-status Reporting-MTA: dns; mail.mindmatics.com Original-Envelope-ID: ABCD1234 Original-Recipient: rfc822; be provided by Xura>.mindmatics.com Final-Recipient: rfc822; be provided by Xura>.mindmatics.com Action: delivered Status: Page: 10 of 13

11 4.5 Request disposition notifications via RFC Composed TO be provided by Xura>.mindmatics.com FROM SUBJECT from=xura CONTENT This is a test message with notification RFC requested message as plain source text Message-ID: < @company.de> Date: Wed, 14 May :05: From: Testuser <testuser@company.de> Content-Type: text/plain; charset=iso To: @<will be provided by Xura>.mindmatics.com Subject: from=xura Disposition-Notification-To: notification_to@company.de This is a test message with notification RFC requested. The Disposition-Notification-To header field is set in this the disposition notification (according to RFC 3798) will be sent to the address notification_to@company.de. Page: 11 of 13

12 4.5.3 Notification example (success) Message-Id: Date: Wed, 14 May :07: From: be provided by Xura>.mindmatics.com To: Subject: Message Disposition Notification MIME-Version: 1.0 Content-Type: multipart/report; report-type=disposition-notification; boundary=frontier --frontier Your message sent from ' ' was SUCCESS. From: Xura To: GUID: F9B2A53G66B1DB8A24CD6717 MyId: JobId: 0 From @<will be provided by Xura>.mindmatics.com To testuser@company.de Message-ID: @company.de Submit date: :06:20 Done date: :06:28 Message type: SMS Status: SUCCESS Detailed error: DELIVERY SUCCESS --frontier content-type: message/disposition-notification Reporting-UA: mail.mindmatics.com; Xura SMTP Interface Original-Recipient: @<will be provided by Xura>.mindmatics.com Final-Recipient: @<will be provided by Xura>.mindmatics.com Original-Message-ID: < @mindmatics.com> Disposition: automatic-action/mdn-sent-automatically; displayed --frontier-- Page: 12 of 13

13 4.5.4 Notification example (error) Message-Id: Date: Wed, 14 May :07: From: be provided by Xura>.mindmatics.com To: Subject: Message Disposition Notification MIME-Version: 1.0 Content-Type: multipart/report; report-type=disposition-notification; boundary=frontier --frontier Your message sent from ' ' was ERROR. From: Xura To: GUID: F9B2A53G66B1DB8A24CD6717 MyId: JobId: 0 From @<will be provided by Xura>.mindmatics.com To testuser@company.de Message-ID: @company.de Submit date: :06:20 Done date: :06:28 Message type: SMS Status: MESSAGE REJECTED Detailed error: ROUTING FAILURE --frontier content-type: message/disposition-notification Reporting-UA: mail.mindmatics.com; Xura SMTP Interface Original-Recipient: @<will be provided by Xura>.mindmatics.com Final-Recipient: @<will be provided by Xura>.mindmatics.com Original-Message-ID: < @mindmatics.com> Disposition: automatic-action/mdn-sent-automatically; deleted/error Error: 002 ROUTING FAILURE --frontier-- Page: 13 of 13