Mail API
The Email-to-SMS API enables you to send SMS via seven by email. Send an email to the gateway, which is then automatically converted into an SMS by us. You can use numerous parameters to control the dispatch and also send messages to contacts or groups.
Setup
In your login in the Developer area under Mail to SMS you can set up the Mail API for your account. You can enter any number of sender addresses, each with a different key.
- 1
Set up sender address
The green + icon at the bottom right of the Mail to SMS area takes you to the window in which you can create a new sender address.
- 2
Set key
You should choose a key for each mail address to make sending more secure. You can freely choose the key, but only lower and upper case letters, numbers and the special characters hyphen, underscore and dollar sign are allowed.
- 3
Error handling
You can also enter an optional e-mail address for receiving error messages here. If you do not specify this, you will receive the error messages to the sender address if you activate the "Notify me of errors" function in the settings (see below). newly set up senders can be used immediately after saving.
- 4
Settings
Click on the blue gear wheels to access the settings options for email to SMS.
Mail API settings
-
Maximum SMS length: Set a maximum number of characters to avoid overlong SMS by sending signatures. Enter 0 to deactivate this function.
-
Remove quotes: If this is activated, the API automatically tries to remove quoted text in the mail.
-
Notify on error: This option determines whether you want to receive a notification by email in the event of any errors. If, for example, the SMS transmission fails or data such as number, key, etc. is incorrect or missing in your email, we will send you an email directly with information about the error. When creating a new sender address, you can optionally enter an alternative email address to which you would like to receive the error messages.
-
Insert sender of the mail in SMS text: Here you can set whether you want to include part of the mail address at the beginning of your SMS. You can choose between three options:
Settings Explanation Full address Inserts the full address, e.g. "einuser@domain.de" Local part of the address e.g. "einuser" is inserted at einuser@domain.de No Does not send the sender address with
SMS dispatch
Structure of the mail
Please use the format described below for your mails to our gateway. If your application cannot be adapted so that the mails can be sent according to this format, contact us - the Mail API is flexibly adaptable!
Recipients
To send an SMS via Mail API, send an email to empfaenger@gateway.seven.io and replace empfaenger with the recipient number or the contact name from your address book.
For example, if you want to send an SMS to the number 01761234567890, the recipient must be 01761234567890@gateway.seven.io.
Subject
In the subject, enter the parameters required to control the SMS dispatch. These should each be separated by a space. To set a parameter, write the name of the parameter, followed by an equals sign and the value of the parameter.
For example, with aParameter=aValue
the parameter aParameter is set to aValue. If the parameter contains spaces, you should enclose it in double quotation marks " - for example aParameter="A value with spaces"
.
Content
The SMS text must be sent in the body of the email. The gateway first uses the text/plain part of the mail. If the mail only contains a text/html part without a text alternative, an attempt is made to parse this and extract the text part from the HTML content. Naturally, this method does not always work as desired.
You can optionally enclose the SMS text with ## to prevent empty lines or the signature of the mail from being included in the SMS text. The text would then look like this: ##This is the SMS text## - only the part between ##...## Is sent in the SMS.
Parameter
- Name
key
- Type
- string
- Description
- The access key that you have specified in your email-to-SMS settings for the respective sender email.
- Name
from
- Type
- string
- Description
- The sender of the SMS. If nothing is specified here, the default sender from your SMS settings will be used. Up to 11 alphanumeric or up to 16 numeric characters are possible.
- Name
to
- Type
- string
- Description
- The recipient of the SMS. If specified, this parameter overwrites the recipient specified in the recipient address of the email. For example, you could send an e-mail to acme-inc@gateway.seven.io with the parameter
to=0176123456789
. The SMS is sent to 0176123456789.
- Name
label
- Type
- string
- Description
- Optionally, set a separate label for each SMS so that you can assign it to your statistics. If not specified, the sender of the email is automatically used as the label. Allowed characters:
a-z, A-Z, 0-9, .-_@
- Name
text
- Type
- string
- Description
- If it is not possible for you to place the SMS text in the content of the mail, you can enter it via the
text
parameter in the subject.
- Name
flash
- Type
- boolean
- Description
- Send a Flash SMS, which is shown directly on the recipient's display and is not saved.
- Name
unicode
- Type
- boolean
- Description
- Allows the SMS to be encoded as Unicode or forces GSM 03.38.
- Name
performance_tracking
- Type
- boolean
- Description
- Activates our URL Shortener and the Performance Tracking for links found in the text.
- Name
foreign_id
- Type
- string
- Description
- Enter your own ID for this message. You will receive the foreign_id back in callbacks for status reports etc. Max. 64 characters, permitted characters:
a-z, A-Z, 0-9, .-_@.
- Name
delay
- Type
- string
- Description
- Schedules the delayed sending of the SMS in the future. Enter either a Unix timestamp or the time in the format YYYY-MM-DD hh:mm:ss.
Security
The transport route between the individual SMTP servers or the SMTP client is generally encrypted using TLS. However, there are several reasons why it makes sense to encrypt the mail, which is why the Mail API supports encryption via PGP and S/MIME:
-
Confidentiality: PGP and S/MIME encrypt the content of emails so that only the intended recipient can decrypt and read them. This ensures the confidentiality of the communication.
-
Authentication: Both standards make it possible to verify the identity of the sender. Digital signatures created with the sender's private key allow the recipient to ensure that the email actually comes from the specified source and has not been tampered with.
-
Integrity: PGP and S/MIME provide mechanisms to verify the integrity of emails. Digital signatures allow the recipient to ensure that the content of the email has not been altered since it was sent.
-
Defense against man-in-the-middle attacks: Through encryption and authentication, PGP and S/MIME help prevent man-in-the-middle attacks, where an attacker intercepts, manipulates and then forwards traffic without the parties involved realizing it.
Overall, PGP and S/MIME are therefore useful for ensuring the security, confidentiality and integrity of email communications, especially in environments where sensitive or confidential information is exchanged.
To send encrypted emails, please download the relevant certificate and install it on your system. As PGP and S/MIME certificates can only be bound to a single e-mail address, please send your e-mails to the e-mail address specified below for the certificate.
You must enter data such as the recipient of the SMS in the subject line using the relevant parameters, e.g. to=017612345678
.
DMARC, DKIM, SPF
DKIM, SPF and DMARC are mechanisms for improving email security. They help to check the authenticity of emails, combat spam and phishing and improve the deliverability of emails.
The Mail API rejects emails if they do not meet the authentication standards defined by your DKIM, SPF and DMARC configuration. This may be the case, for example, if an email does not have a valid DKIM signature, the sender's IP address is not authorized in the SPF records or the domain owner's DMARC guidelines require the rejection of unauthenticated emails.
Please take this into account when implementing the Mail API. You can view rejected emails in your Debugger.
Examples
First example
In the first example, an SMS is sent to the phone number 0163123456789 from the sender ZahnPraxis. The key in this case is email2sms_key.
The text to be transmitted in the SMS is:
Hello Mr. Schubert, we would like to remind you of your appointment on January 20 at our practice. We look forward to seeing you! Until then, your dental practice
Second example
In this second example, an SMS is sent to the contact Bartscher from the sender Optiker. The default for the number 0163123456789, which is in the recipient of the mail, is overwritten by the parameter to
. The key here is 123456789.
The text to be transmitted in the SMS is:
Hello Mrs. Bartscher, your glasses are ready! Please collect them from us soon. We look forward to seeing you! Until then, your opticians - the signature of the e-mail below will not be sent in the SMS, as the text is enclosed by ##.
Third example
In this example, an SMS is sent to the phone number 0163123456789. The settings for the sender are used from the default settings of your account under Settings > SMS. The key is integrated directly in the recipient of the mail and set to abcd123456.
The text to be transmitted in the SMS is:
Hello Mrs. Bartscher, your glasses are ready! Please collect them from us soon. We look forward to seeing you! Until then, your opticians
The signature of the e-mail below is not sent in the SMS, as the text is enclosed by ##.
Legacy
For reasons of downward compatibility, the gateway will remain available under the old recipient address email2sms@sms77.de for mails in the former format. The mails will continue to be processed as usual. However, we recommend switching to this new API in order to be able to use the full range of functions.