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. 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. 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. 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. 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:

    SettingsExplanation
    Full addressInserts the full address, e.g. "einuser@domain.de"
    Local part of the addresse.g. "einuser" is inserted at einuser@domain.de
    NoDoes 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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

Mail-to-SMS first example

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.

Mail-to-SMS second example

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.

Mail-to-SMS third example

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.