Project

General

Profile

Wiki » 04 Transmission communication channels and API »

01 Email Description

  1. Email is one of the transmission channels Docura uses to exchange business documents with partners. Two independent mechanisms are involved:
    1. Incoming - a mailbox on the Docura mail server where partners send documents for automatic parsing and delivery into Docura (section 02).
    2. Outgoing - notifications that Docura sends to partners when a document is received or sent, with the document itself as an attachment (section 03).
  2. Email is convenient because the partner needs no EDI software, no FTP account and no certificates - a mailbox is enough. This makes email the fastest way to connect a counterparty that has no EDI at all.
  3. The weak points of email are deliverability (SPF, DKIM and DMARC of the sender domain, see section 06) and the fact that mail clients compose letters in very different ways (see section 02).

02 Incoming email gateway (parsing)

  1. For incoming documents Docura creates a mailbox on its own mail server, in the domain @edi.docura.net. The mailbox is created by Docura support in the mail server admin panel - the sender only needs to know the address.
  2. Naming is agreed with Docura support. Typical patterns:
    1. - the standard case, one gateway per counterparty. The company name is written without spaces and short readable abbreviations are fine (for example ep@ for Eesti Pagar).
    2. - when several countries or formats are involved, for example
    3. - when document types are handled separately, for example
  3. The mailbox is monitored: Docura periodically collects the letters, extracts the content, converts it into the agreed format and delivers the document into the client's Docura environment. This also works for counterparties that do not want a real EDI connection at all - sometimes called "blind" EDI.
  4. There is no strict rule about the letter itself - the sender does not have to send one document per letter:
    1. A letter may contain several documents, or a single archive (for example zip) with many files inside - everything is picked up and processed.
    2. What has to match is the agreed document layout and format, not the number of files per letter.
  5. Content that can be parsed:
    1. Excel price lists - loaded as PRODUCTCATALOG / PRICAT (the layout is agreed in advance)
    2. XML documents - Docura XML or another agreed format (INVOICE, ORDER, DESADV and others)
    3. Other formats by agreement - EDIFACT, CSV, Telema/Edisoft XML
  6. Two modes of taking the document out of the letter (chosen per relation together with Docura support):
    1. Attachment - all attachments of the letter are taken one by one and each one is processed. This is the usual mode.
    2. Body - the whole letter is converted into XML and processed. Used when the data sits in the letter text rather than in a file.
  7. Filters decide what is accepted and what is ignored. They are configured by Docura on the relation:
    1. Sender filter (regular expression) - accept letters only from an agreed address mask.
    2. Subject filter (regular expression) - accept letters only with a matching subject.
    3. File name filter (regular expression, for example (?i)(.*)(.xls|.xlsx)) together with the file filter type (for example Error without notification). This exists because senders often add logos, pictures and signatures, while every attachment is processed - the filter cuts such files off.
  8. So the sender needs no special discipline: it is enough to send to the agreed address, and the odd extra file will simply be filtered out instead of breaking the parsing.
  9. What does not pass the filters is not lost: where the relation is configured that way, the letter is forwarded unchanged to the error address, with the original From and To moved into the subject (otherwise such a letter would end up in spam).
  10. The original letter can also be forwarded to the client (Copy email) - used when free-format letters have to be seen by a human.
  11. A working example is Fristar_SIA: the address accepts price lists (Excel) and XML invoices, and the page describes the whole flow from the partner's side.
  12. The gateway is not meant for mass mailings: the receive rate is limited (about 150 letters per minute). Above that the letters go to the reject log and the sender is blocked for 24 hours. Bulk exchange is done over FTP or API.

03 Outgoing notifications

  1. Outgoing letters are notifications about documents. A notification is configured per relation: document type, document status, direction and partner, so one organization may have several notifications with different settings.
  2. Recipients are collected from several sources:
    1. To - the receiver e-mail taken from the document itself (Document-Invoice/Document-Parties/Receiver/E-mail)
    2. plus any addresses listed explicitly in the notification
    3. plus, for some partners, addresses taken from the receiver LOCCAT - used when one invoice must be delivered to many shops or delivery points
  3. Reply-to is taken from the sender e-mail in the document (Document-Invoice/Document-Parties/Sender/E-mail), so the partner's answer reaches the right person.
  4. The letter body is built by an XSLT template (Email xslt), and the document can be attached as a file.
  5. By default all notifications are sent from the Docura domain: .

04 SMTP connection settings

An SMTP connection is the stored set of credentials that tells Docura which mailbox and which server to use for sending. It is created and maintained in the Docura web application (tab Notifications, window Update smtp connection):

Field Meaning
Description Free comment, usually the mail server name
serverName SMTP server host of the sender mailbox
serverPort SMTP port, usually 25, 465 or 587
Username The mailbox login, i.e. the address the mail is really sent from
User password Password of that mailbox
Connection security Encryption mode, usually SSL_TLS
  1. The button Test connection verifies the saved credentials before the notification is switched over.
  2. An SMTP connection can also be created through the API (operation createSmtpConnection): organizationId, description, fromName, serverName, serverPort, userName, userPassword, connectionSecurity.

05 Notification settings in EDI-Web

Sender addresses are not global - they are set on the notification itself: Notifications - Edit, tab Notification information.

Field Meaning
Email Recipient address(es) of the notification
From name (name <email>) The address the notification is sent FROM
Reply to (name <email>) The address the partner's answer will go to
Partner Partner organization the notification belongs to
Smtp connection Which SMTP connection (mailbox) is used for sending
Email xslt XSLT template that builds the letter body
Enabled Enabled / disabled
  1. The tab SMTP shows the connection used by this notification, the tab XSLT shows the template.
  2. Recipients that are not in the document itself can be added additionally in the notification, see section 03.

06 Which sender address is used

  1. Default: the Docura domain. From = , Reply to = the client's address. Deliverability is guaranteed, because the Docura domain has correct SPF, DKIM, DMARC and PTR records. This covers most cases and is the recommended setup.
  2. From = the client's own domain. Two options:
    1. Through the client's own mail server - the client's SMTP server, login and password are stored as the SMTP connection. SPF and DKIM of the client domain pass, because the mail is really sent by their server. This is the safest option for a client From.
    2. Through the Docura mail server, keeping the client's address in From. Then the client's DNS must be prepared first, otherwise such letters go to spam or are rejected:
      TXT mail._domainkey "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq4dvMit/5L1okysL1nzm3d+qsl1XYeEg8sUzuBHSWRzX8UQ2Xai6cYukmBU7N4Brn69+1xc8DbdUwlP1mpiYhf2qTK7yaYjZTnfyyyumTCFhkHGDfJmga6p2JsOIUQ5dFhlE4gQBUI4FY3a3XZM2gbUVTr08dGkpEJA3yrsbJ5akl88tJsvX4Osw1EJl6i9dn" "1yzX+VxFlD6imjDDgYvyu2sxzWhU6dGtvg7KsP+8x0mXXp9gGFT/odo5zbLjmD0VT9KMWNwRUlBAsOT7bCJgauEXk9ygSnCazZ5UpmGgKfPuXIEXGTEUzRSblTNqKsUjGZtdiWxBo2FXPqnT+AIPwIDAQAB" 

TXT @ "v=spf1 ip4:78.46.44.41 ip4:78.46.44.49 ip4:178.63.30.140 a mx ~all" 

TXT _dmarc "v=DMARC1;p=none"

01 Through Docura, keeping the client's address in From. DNS

DNS records for a client From (SPF, DKIM, DMARC). Needed only for option 2.2 above. All three are TXT records on the same domain that is used in From - @@ means the root of that domain, not a subdomain.

01 SPF

Only one SPF record is allowed per domain. If you already have one, do not create a second - add the Docura addresses to the existing record, keeping everything that is already there.

TXT @ "v=spf1 ip4:78.46.44.41 ip4:78.46.44.49 ip4:178.63.30.140 a mx ~all"

~all is the soft mode - mail from other addresses is marked as suspicious but delivered. -all rejects it, so with -all every sender of the domain must be listed.

02 DKIM

A new record, it replaces nothing. mail is the selector, so other services signing mail for your domain are not affected.

TXT mail._domainkey "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq4dvMit/5L1okysL1nzm3d+qsl1XYeEg8sUzuBHSWRzX8UQ2Xai6cYukmBU7N4Brn69+1xc8DbdUwlP1mpiYhf2qTK7yaYjZTnfyyyumTCFhkHGDfJmga6p2JsOIUQ5dFhlE4gQBUI4FY3a3XZM2gbUVTr08dGkpEJA3yrsbJ5akl88tJsvX4Osw1EJl6i9dn" "1yzX+VxFlD6imjDDgYvyu2sxzWhU6dGtvg7KsP+8x0mXXp9gGFT/odo5zbLjmD0VT9KMWNwRUlBAsOT7bCJgauEXk9ygSnCazZ5UpmGgKfPuXIEXGTEUzRSblTNqKsUjGZtdiWxBo2FXPqnT+AIPwIDAQAB"

Two quoted strings because one TXT string cannot exceed 255 characters - DNS joins them when read.

03 DMARC

Only one DMARC record is allowed per domain. If you already have one, leave it as it is. The record below is only for domains that have none.

TXT _dmarc "v=DMARC1;p=none"

04 PTR and HELO

Belong to the Docura sending servers, not to your domain. Maintained by Docura, nothing to do on your side.

05 After adding

DNS changes take from a few minutes up to 24 hours depending on the TTL. When the records are visible, ask Docura support for a test letter, see section 07. Until it passes, keep sending from the Docura domain.

07 Test and support

  1. Ask Docura support to send a test letter to the client's address and check the raw headers (From, Reply-to, SPF/DKIM/DMARC result).
  2. For the incoming gateway, send one order or invoice (a normal letter, with whatever extra files your mail client adds) to the edi.docura.net address and ask support to confirm that it was parsed correctly.
  3. Write to or use the chat in EDI-Web for any question on gateway mailboxes, filters, sender addresses and DNS records.