Mail API

The Mail API allows you to send SMS, RCS, and soon also voice messages via seven by mail. Send an email to the gateway, which is then automatically converted into a message by us. Numerous parameters allow you to control the dispatch specifically and also send messages to contacts or groups.

Setup

In your login in the Developer section under Mail API, you can set up the API for your account. You can specify any number of sender addresses, each with a different key.

  1. 1

    Set up sender address

    Via the green + icon at the bottom right in the Mail API area, you can access the window where you can create a new sender address.

  2. 2

    Define key

    You should choose a key for each email address that makes the dispatch more secure. You can freely choose the key, but only lowercase and uppercase letters, numbers, and the special characters hyphen, underscore, and dollar sign are allowed.

  3. 3

    Error handling

    You can also specify an optional email address for receiving error messages here. If you do not specify this, you will receive the error messages on the sender address if you activate the "Notify in case of errors" function in the settings (see below). Newly set up senders can be used immediately after saving.

  4. 4

    Settings

    By clicking on the blue gears, you can access the settings options for the Mail API.

Mail API Settings

  • Maximum length: Set a maximum character count to avoid overly long messages by sending signatures. Enter 0 to disable this function.
  • Remove quotes: If this is activated, the API automatically tries to remove quoted text in the mail.
  • Notify in case of error: This option determines whether you want to receive a notification by mail in case of any errors. For example, if the message dispatch fails or data such as number, key, etc. in your email were incorrectly specified or missing, we will send you an email with information about the error. When setting up a new sender address, you can optionally specify an alternative email address to which you would like to receive the error messages.
  • Insert sender of the mail into text: Here you can set whether you want to send part of the email address at the beginning of your message. You can choose between three options:
SettingsExplanation
Full AddressInserts the complete address, e.g. "auser@domain.de"
Local part of the addressFor example, "auser" is inserted for auser@domain.de
NoDoes not send the sender's address

Send Message

Structure of the Mail

Please use the format described below for your mails to our gateway. If your application cannot be adapted to send mails according to this format, contact us - the Mail API can be flexibly adapted!

Recipient

To send a message via the Mail API, send a mail to recipient@gateway.seven.io and replace recipient with the recipient's number or the contact name from your address book.

For example, if you want to send a message to the number 441761234567890, the recipient must be 441761234567890@gateway.seven.io.

Subject

In the subject, you enter the required parameters for controlling the message 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 message text must be sent in the body of the email. The gateway first uses the text/plain part of the mail for this. If the mail only contains a text/html part without a text alternative, it tries 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 message text with ## to prevent empty lines or the signature of the mail from being included in the message. The text would then look like this: ##This is the text## - only the part between ##...## is sent in the message.

Parameters

All parameters are specified in the subject of the email as mentioned above. If it is not possible for you to change the subject of the mail, you can also enter the parameters in the recipient address as follows:

  • 441761234567890.from=Dentist@gateway.seven.io
  • 441761234567890.from=Dentist.type=rcs@gateway.seven.io
  • key=MAIL_API_KEY.from=Dentist.to=441761234567890@gateway.seven.io

Here is an overview of the possible parameters:

  • Name
    key
    Type
    string
    Optional
    Optional
    Description
    The access key, which you have specified in your Mail API settings for the respective sender email.
  • Name
    from
    Type
    string
    Optional
    Optional
    Description
    The sender of the message. If nothing is specified here, the default sender from your SMS settings is used. Up to 11 alphanumeric or up to 16 numeric characters are possible.
  • Name
    to
    Type
    string
    Optional
    Optional
    Description
    The recipient of the message. This parameter overrides, if specified, the recipient, which was specified in the recipient address of the mail. Thus, you could send a mail to acme-inc@gateway.seven.io with parameter to=0176123456789. The message is sent to 0176123456789.
  • Name
    label
    Type
    string
    Optional
    Optional
    Description
    Optionally set your own label for each message to be able to assign them in 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
    Optional
    Optional
    Description
    If it is not possible for you to place the message text in the content of the mail, you can enter it via the text parameter in the subject.
  • Name
    flash
    Type
    boolean
    Optional
    Optional
    Description
    Send a Flash SMS, which is displayed directly on the recipient's display and is not saved. Only for the message type SMS.
  • Name
    unicode
    Type
    boolean
    Deprecated
    Deprecated
    Optional
    Optional
    Description
    Allows the encoding of the message as Unicode or forces GSM 03.38.
  • Name
    performance_tracking
    Type
    boolean
    Optional
    Optional
    Description
    Activates our URL shortener and the Performance Tracking for links found in the text.
  • Name
    foreign_id
    Type
    string
    Optional
    Optional
    Description
    Specify your own ID for this message. You will receive the foreign_id back in callbacks for status reports etc. Max. 64 characters, allowed characters: a-z, A-Z, 0-9, .-_@.
  • Name
    delay
    Type
    string
    Optional
    Optional
    Description
    Plans the delayed sending of the message in the future. Here, either enter a Unix Timestamp or the time in the format YYYY-MM-DD hh:mm:ss.
  • Name
    type
    Type
    enum
    Optional
    Optional
    Description
    Specify the type of message you want to send. Possible here are sms (standard), rcs and soon also voice.

Security

Although the transport path between the individual SMTP servers or the SMTP client is usually encrypted by TLS, encrypting the mail is sensible for several reasons, 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 communication.

  2. Authentication: Both standards allow the sender's identity to be verified. 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 manipulated.

  3. Integrity: PGP and S/MIME provide mechanisms for verifying the integrity of emails. Digital signatures allow the recipient to ensure that the content of the email has not been changed since it was sent.

  4. Defense against Man-in-the-Middle attacks: Encryption and authentication with PGP and S/MIME help prevent Man-in-the-Middle attacks, where an attacker intercepts, manipulates, and then forwards the traffic without the parties involved noticing.

Overall, PGP and S/MIME are therefore useful for ensuring the security, confidentiality, and integrity of email communication, especially in environments where sensitive or confidential information is exchanged.

For encrypted sending of mails, please download the respective certificate and install it in your system. Since PGP and S/MIME certificates can only be tied to a single email address, please send your emails to the email address specified below for the certificate.

You must specify data such as the recipient of the message in the subject via the respective parameters, such as to=017612345678.

This procedure is not secure, as the data in the headers of the mail are sent unencrypted. We are already working on an alternative solution.

Here you can download the respective certificate:

PGP

Download Certificate

Mail Address: gateway@gateway.seven.io

S/MIME

Download Certificate

Mail Address: mail@gateway.sms77.io

DMARC, DKIM, SPF

DKIM, SPF, and DMARC are mechanisms to improve email security. They help verify the authenticity of emails, combat spam and phishing, and improve email deliverability.

The Mail API rejects mails if they do not meet the authentication standards set by your configuration for DKIM, SPF, and DMARC. This can 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 entries, or the DMARC policies of the domain owner provide for the rejection of unauthenticated emails.

Please keep this in mind when implementing the Mail API. Rejected mails can be viewed in your Debugger.

Examples

First Example

In the first example, an SMS is sent to the phone number 0163123456789 from the sender DentalPractice. The key in this case is email2sms_key.

Mail-to-SMS first example

The text to be transmitted in the SMS is:

Dear Mr. Schubert, we would like to remind you of your appointment on January 20th at our doctor's office. We look forward to seeing you. Sincerely, your dentist.

Second Example

In this second example, an SMS is sent to the contact Bartscher from the sender Optician. The specification for the number 0163123456789, which is in the recipient of the mail, is overwritten by the to parameter. The key here is 123456789.

Mail-to-SMS second example

The text to be transmitted in the SMS is:

Hello Ms. Bartscher, your glasses are ready! Please pick them up soon. We look forward to seeing you! Best, your opticians.

The signature of the mail below is not included 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 taken from the default settings of your account under Settings > SMS. The key is directly integrated 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 Ms. Bartscher, your glasses are ready! Please pick them up soon. We look forward to seeing you! Best, your opticians.

The signature of the mail below is not included in the SMS, as the text is enclosed by ##.

Legacy

For reasons of backward compatibility, the Mail API remains 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 to be able to use the full range of functions.

Last updated: 1 month ago