i) Email Configuration
- Leonard Schubert
WebSignatureOffice Emails
- 1 WebSignatureOffice Emails
- 1.1 Mail overview
- 1.1.1 Document mails
- 1.1.2 Envelope Mails
- 1.1.3 Signature Field mails
- 1.2 Mail content details
- 1.3 Document emails
- 1.4 Signature field Mails
- 1.5 Envelope Mails
- 1.6 User emails
- 1.7 System emails
- 1.8 Support emails
- 1.1 Mail overview
- 2 Server configuration
- 3 Email customization
- 3.1.1.1 Add mail templates
- 3.1.2 Document / Envelope Links and Landing page
- 3.1.3 url_guest
- 3.1.4 url (registered user link)
- 3.1.5 custom landing page
- 3.2 mail subjects:
- 4 SMS
Mail overview
The following overview shows, to whom mails regarding a document or envelope are sent.
indicates, that the emails are sent to the specified document/envelope user type
indicates that the mails are not sent to the specified document/envelope user type
indicates, that the mails are only sent to the specified document/envelope user type when certain conditions are met
The mail types are described in the section “mail content details” below.
Document mails
If a document belongs to an envelope which was created via tyrservice, the mails “notify_signers” and “observer” are not sent. Instead only the envelope mails “notify_signers_envelope” and “observer_envelope” are sent.
If the documents belong to an envelope created via the UI, the “notify_signers” and “observer” mails are sent for each document when created and the “notify_signers_envelope” and “observer_envelope” are sent, when creating the envelope.
creator | registered user | guest user | observer | note | |
|---|---|---|---|---|---|
notify_signers | Notification mail, when a signature request is created for users who have signatures in the document. If a signatureOrder is defined and the creator has signatures in the document and is not on position 1, he will receive the email when it’s his turn. | ||||
observer | Pendant to the nofity_signers mail for an observer. | ||||
signature_request_failed | Notification mail, when a signature request failed. If a signatureOrder is defined, a user only receives a signature_request_failed email, when he is on or below the active signatureOrder position. | ||||
signature_request_upcoming_due | Reminder mail sent three days before the due date of a signature request. If a signatureOrder is defined, a user only receives a signature_request_upcoming_due mail, when he is on or below the active signatureOrder position. | ||||
user_finished | Notification that a user has signed/rejected all his signature fields in a document. If the config mail_sent_to_registered_users is true, also registered users who are not creators receive the notification. | ||||
signature_request_finished | This email i sent when a document is finished. If the document is part of an envelope, no notification for single documents are sent, but an signature_request_envelope_completed mail is sent when all documents in the envelope are completed (see below). |
Envelope Mails
creator | registered user | guest user | observer | note | |
|---|---|---|---|---|---|
notify_signers_envelope | If a signatureOrder is defined and the creator has signatures in the document and is not on position 1, he will receive the email when it’s his turn. If an envelope is created via tyrservice, no notify_signers mails for the individual documents are sent. | ||||
observer_envelope | Pendant to notify_signers_envelope mail for an observer. If the envelope was created via tyrservice, no document observer mail (“observer”) will be sent for the documents of the envelope. | ||||
observer_envelope_completed | Pendant to signature_request_envelope_completed for an observer. | ||||
signature_request_envelop_upcoming_due | Reminder mail sent three days before the due date of the signature requests in an envelope. If a signatureOrder is defined, a user only receives a signature_request_envelop_upcoming_due email, when he is on or below the active signatureOrder position. | ||||
signature_request_envelope_completed | Sent when all signature requests in an envelope are completed (failed or finished) |
Signature Field mails
Signature field mails are sent for each signature field in a document or envelope when a user signs or rejects it.
creator | registered user | guest user | observer | note | |
|---|---|---|---|---|---|
signature_field_signed | Notification mail, when a user rejects or signs a signature field. If the config mail_sent_to_registered_users is true, also registered users who are not creators receive the notification. Also sent for each signature fields of envelopes. | ||||
signature_field_rejected |
Mail content details
Emails contain information about the receiver.
If the email notification was triggered by the actions of a user, it also contains “sender” information.
Emails contain links and names if they are associated with an envelope or document.
receiver / sender | document/envelope |
|---|---|
registered and active user:
guestuser associated with a document
please note: Unregistered users which are added as a signer to a signature request via tyrservice.processXml neither have a firstname/lastname nor a guestname. Only a generic greeting can be generated. |
only if due is defined for envelope/document:
only for envelope:
|
In the tables below “Information” defines the objects (user/envelope/document) as described above with the associated fields. Additional Information about email-types are also listed in the description:
Document emails
mail name | description |
|---|---|
notify_signers | A notify_signers email is sent, when a signature request is created or when the tyrservice method resendNotifySigner is called. In that case signatureOrder will be ignored and the email will be sent even if it is excluded. Information:
sent to:
please note: If an envelope is created via the UI, all users receive notify_signers emails and a notify_signers_envelope email. If an envelope is created via tyrservice, only notify_signers_envelope emails are sent. please note: If the signature request was created via UI and a guest signer was invited, no notify_signers email will be send for that user. An invitation mail with a link to the registration page will be sent. The user can just sign the document, if he registers for websignatureoffice. |
observer | Notification mail for an observer of a document. The observer can be set in UI signatureRequest creation or via tyrservice. Information:
sent to:
please note: If an envelope is created via the UI, all observer receive observer emails and a observer_envelope email. If an envelope is created via tyrservice, only observer emails are sent. |
signature_request_failed | A signature_request_failed message is send to all users of a document if it failed because mandatory fields were rejected, the request was stopped or the due date passed. Information:
sent to:
|
signature_request_finished | A signature_request_finished mail is when the signature request of a document is finished. Information:
sent to:
|
signature_request_upcoming_due | A signature_request_upcoming_due mail is send three days before the due date passes. Information:
sent to:
|
user_finished | A user_finished mail is sent, if a user finished all signatures in the document Information:
sent to:
|
Signature field Mails
mail name | description |
|---|---|
signature_field_signed | A signature_field_signed email is send to registered users if another user signed a signaturefield Information:
sent to:
please note: This email is sent for every signed signature field and may lead to allot of emails. It is advised to deactivate it. See Server configuration below. |
signature_field_rejected | A signature_field_rejected email is sent to registered users if another user rejects a signature field in the document Information:
sent to:
|
Envelope Mails
mail name | description |
|---|---|
notify_signers_envelope | A notify_signers_envelope mail is sent when an envelope is created or when the tyrservice method resendNotifySignerEnvelope is called. In that case signatureOrder will be ignored and the email will be sent even if it is excluded. Information:
sent to:
please note: If an envelope is created via the UI, all users receive notify_signers emails and a notify_signers_envelope email. If an envelope is created via tyrservice, only notify_signers_envelope emails are sent. |
observer_envelope | An observer_envelope mail is sent when an envelope is created. Information:
sent to:
please note: If an envelope is created via the UI, all observer receive observer emails and a observer_envelope email. If an envelope is created via tyrservice, only observer emails are sent. |
signature_request_envelop_upcoming_due | A signature_request_envelope_upcoming_due email is sent when one signature request of the envelope is due in three days. Information:
sent to:
|
signature_request_envelope_completed | A signature_request_envelope_completed email is sent, when all signature requests of an envelope are either failed or finished. Information:
sent to:
|
observer_envelope_completed | A observer_envelope_completed email is sent, when all signature requests of an envelope are either failed or finished. Information:
sent to:
|
User emails
mailtype | description |
|---|---|
invitation | An invitation mail is sent to a non registered user, when a registered user invites. This can be done when creating a signature request or by inviting the user as a contact. Information:
sent to:
Please note: If the invitation is sent with a signature request no notify_signers mail will be sent to the user. The document information are contained in the invitation mail. |
invitation_accepted | An invitation accepted mail is sent when a user accepts an invitation which was sent by another user. Information:
sent to:
|
friend | A friend mail is sent, when a user requests another registered user as a contact. Information:
sent to:
|
friend_accepted | A friend_accepted email is sent when a registered user accepts a friend request Information:
sent to:
|
System emails
mailtype | description |
|---|---|
email_validation | An email validation mail is sent when a user registers at websignatureoffice. The user has to confirm the email adress by clicking the verification link and entering the token. Information:
sent to:
|
password_reset | A password_reset email is sent, when a user forgot his/her password and wants to set a new one. Information:
sent to:
|
registration | A registration mail is send after a registered user registered a user via tyrservice or usermanagement. The email contains a link and token to verify the email address. Information:
sent to:
|
notify_account_charge | Notification when a user account was charged by an admin user. Information:
sent to:
|
Support emails
mail name | description |
|---|---|
support | A support email is sent when a user writes a message int the support form. The support email contains the message the user entered and is a confirmation that the support request was received. The support form is located at
Information:
sent to:
message_type can be
Please note: As a person who requests support my not have an account, the receiver.id may not be present. |
support_internal | A support email is sent when a user writes a message int the support form. It is send to the support of the company. The emails are defined in the server config “support_email” Information:
sent to:
|
Server configuration
The email configuration is done in the frigg config.ini.
General settings
To activate automatic email notifications the following configs must be set.
key | example | description |
|---|---|---|
emailFrom | the from mail header added to emails sent by the system | |
emailPort | 25 | the smtp port |
emailRetries | 5 | how many times the mailer retries to sent an email. Default 3. |
emailSmtp | hostname.domain or "false" | the smtp server used to sent mails. If set to "false", sending mails will be deactivated entirely. |
emailSmtpPassword | password | the smtp server password |
emailSmtpUser | smtpuser | the login for the smtp server |
emailTls | false | true or false, enable or disable TLS (encryption) |
Additional Settings
key | example | description |
|---|---|---|
support_email | support@websignatureoffice.com | the email address for support notifications / inquiries as described in support emails above. |
admin_email_notifier | foo@host.com;bar@host.com | a list of recipients who are informed when accounts are charged with help of the admin functions or when user bought credits as described system emails above |
mail_excluded_type | signature_field_signed;notify_signers | semicolon seperated list of email types which should be excluded. All mail types can be excluded. |
mail_html_only | true/false | If true only html mails are send If false also text mails are send. Default is false. |
mail_sent_to_registered_users | signature_field_signed;user_finished | semicolin seperated list of mailtypes. Possible mailtypes:
By default the mails are only sent to the creator of the document/envelope. Mail types defined in mail_sent_to_registered_users will be sent to every registered/active user associated with the document/envelope. This setting may be used, if all documents are uploaded via tyrservice with one user but the employees have registered users. |
Email customization
Example Email Template customization | Unprocessed template example |
|---|---|
...
<body>
<div class="container">
<img src="data:image/png;base64,{{new_logo_base64}}" class="logo" alt="Example Company Logo">
<h1>Dear
<#if receiver.lastname?has_content>Mr. ${receiver.lastname},
<#elseif receiver.guestname?has_content>${receiver.guestname},</#if>
</h1>
<p>Thank you for using our company.</p>
<p>Your account manager ${sender.firstname} ${sender.lastname} has compiled the following documents for the <strong>${envelope.name}</strong> for you:</p>
<ul>
<#list envelope.documents as document><li>${document.name}</li></#list>
</ul>
<p>The offer is valid until ${envelope.dueDate?string("dd.MM.yyyy")}</p>
<p>Please click on the following link to retrieve the document:</p>
<a href=${envelope.urlGuest}>Sign Documents</a>
</div>
<div class="footer">
Example Company GmbH<br>
ExampleStreet 123, 10115 Berlin<br>
Handelsregister: Amtsgericht Berlin, HRB 123456<br>
USt-ID: DE123456789
</div>
</body>
</html> |
WebsignatureOffice provides email templates but it is possible to define customized templates.
The emails are constructed with freemarker https://freemarker.apache.org/
The templates names constructed with the mail name the suffix “mail” the type (“html” or “text”) and the locale concatenated with an underscore with the file extension *.ftl. E.g. notify_signers email must have the file names
notify_signers_mail_html_de.ftl //german html mail
notify_signers_mail_html_en.ftl //english html mail
notify_signers_mail_text_de.ftl //german text mail
notify_signers_mail_text_en.ftl //english text mailIf the config html_mails_only is set to false, text mail templates must be provided.
The information described in the email overview can be used to construct freemarker templates.
The objects defined above are adressed with the object name and the field name.
e.g.
{$document.name}
{$receiver.firstname}
{$envelope.id}
{$sender.encryptedId}
{$envelope.url}For date objects, the format of the date must be provided.
e.g
To retrieve information about the documents in an envelope, it’s possible to iterate over the document list.
e.g.
Please note that not all fields are present in every email, so it is advised to wrap them with if-statements as followed:
Some templates have additional fields (e.g. “amount” in notify_account_charge). These fields are adressed directly without an object reference:
Example freemarker template for the standard WebSignatureOffice“notify signers” email:
Example template as HTML-file to view in Browser:
Add mail templates
If you use software as a service, you have to provide the mail templates and they will be added to the database by us.
If you host on Prem, you can add the files yourself.
The custom email templates must be stored in the table mail_template as a blob. The mail_type_id references the id of the table mail_type. The files can be insertet with LOAD_FILE(“path/to/file”).
The template names must be set as described above. The mail_subject may be empty (see below). The locale must correspond to the locale in the file name.
Example for mail_type 1 (notify_signers):
The referenced mail_type_ids are as followed. Mailtype 100 - 103 are described below in section SMS.
1 | notify_signers |
2 | signature_field_signed |
3 | signature_field_rejected |
4 | signature_request_failed |
5 | signature_request_finished |
6 | signature_request_reminder1 (deprecated) |
7 | signature_request_reminder2 (deprecated) |
8 | signature_request_reminder3 (deprecated) |
9 | invitation |
10 | invitation_accepted |
11 | signature_request_deleted |
12 | friend |
13 | friend_accepted |
14 | credits_expired |
15 | observer |
16 | signature_request_stopped |
17 | signature_request_upcoming_due |
18 | registration |
19 | invoice |
20 | support |
21 | notify_signers_envelope |
22 | observer_envelope |
23 | user_finished |
24 | signature_request_envelope_completed |
25 | signature_request_envelope_upcoming_due |
26 | email_validation |
27 | password_reset |
28 | notify_account_charge |
29 | internal_support |
30 | observer_envelope_completed |
100 | sms_verification_url |
101 | sms_auth |
102 | sms_verification |
103 | sms_document_link |
Document / Envelope Links and Landing page
url_guest
The envelope.urlGuest and document.urlGuest are standalone viewer links (TimeLimitedDocumentViewer and TimeLimitedEnvelopeViewer)
The link is valid till the signature request due date plus the timespan defined in the config “guest_user_document_availability” in days.
url (registered user link)
The envelope.url and document.url refer to the viewer, which is integrated in the graphical user interface. If the user is not logged in websignatureoffice, he is redirected to the login page.
A registered user link (field “url”) is only present, if the user is registered. The “urlGuest” is always provided. If you want to use the document.url you should define document.urlGuest for non active user:
custom landing page
With the provided envelope_id / document_id and user_id it is possible to construct a link to your own landing page on which you can implement the viewer links or the viewer as an iframe. d) Integration Document and Envelope Viewer
e.g.
mail subjects:
If no subject is defined via the UI, websignatureoffice provides default mail subjets.
It is possible to define custom mail subjects in the table mail_template. The table is described above. If you are using SAAS, you have to provide us the mail_subjects for the different mail types / language.
If you’re hosting yourself, you can add the mail subjects in the table mail_template as described above.
SMS
template | description | websignatureOffice default (en) |
|---|---|---|
sms_auth | A onetime token to open a SMS protected envelope or document Fields
|
mail_type_id: 101 |
sms_document_link | A shortened URL to a standalone document viewer or envelope viewer. The SMS is sent when signing synchrone remote with SMS link. Fields
|
mail_type_id: 103 |
sms_verification | Used to verify the mobile number of registered users. Fields
|
mail_type_id: 102 |
Configuration
key | example | description |
|---|---|---|
sms_token_characters | alphanumerical_casesensitive | Defines which characters are used in an sms_auth SMS. Possible values
Default is alphanumerical_casesensitive |
sms_token_length | 6 | The length of the sms token. Default is 6. |
smsUserId |
| UserId for the SMS Provider. |
smsSender | Stepover | Name of the SMS sender shown on the mobile device. |
authToken |
| Authentification token for the SMS provider. |
smsPassword |
| Password for the SMS provider. |
credit_sms_identification | 1 | Cost of user SMS identification in credits. |
Custom templates
By default the websignatureOffice templates are used. You can add custom sms templates in the table mail_templates.
Custom sms templates don’t have a *_html.ftl file but only *_text.ftl. Also the “mail_subject” won’t be processed. Templates are added like mail_templates as described in the section Email Customization.
WebsignatureOffice SMS Provider
WebsignatureOffice uses SMS API für Unternehmen | Massenversand as the SMSProvider.
The parameters to send the sms are
mobile: The receiver number of the user.
sender: The sender name defined in config smsSender
msg: The message constructed based on the provided templates
authToken: The token defined in the config authToken
msgtype: The message type (t=160 characters)
The URL is constructed via freemarker with the template sms_verification_url. If the template isn’t present in the database, the default template is used.! It does not need any suffix or prefex and no locale.
To use the sms provider, you have to provide your credentials in the config.ini.
Other SMS provider (experimental)
It is possible to use a SMS provider of your choice. Only limitation is, that the providers API doesn’t need a request body but only url parameter. You can define a sms_verification_url.ftl according to their specification. If the provider doesn’t use auth token but username / userid and password, you can set the configs “smsUserId” and “smsPassword” instead and define the sms_verfication_url.ftl template accordingly.
If the provider’s api needs other credentials, you can also hardcode the credentials in the template sms_verification_url.ftl.
The template sms_verification_url.ftl must be present in the database (mail_type_id 100).
The sms_verification_url.ftl can be populated with the following fields:
name | value | config |
|---|---|---|
message | The message constructed with the templates | optional: sms_template_directory |
sender | YourCompany | smsSender |
authToken | authentication token for SMS provider | authToken |
mobile | mobile number defined via tyrservice or UI | - |
smsUserId | userId for SMS provider | smsUserId |
smsPassword | password for SMS provider | smsPassword |