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
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
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
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
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:
| Settings | Explanation |
|---|---|
| Full Address | Inserts the complete address, e.g. "auser@domain.de" |
| Local part of the address | For example, "auser" is inserted for auser@domain.de |
| No | Does 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 01761234567890, the recipient must be 01761234567890@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
- 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
textparameter 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),rcsand soon alsovoice.
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:
-
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.
-
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.
-
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.
-
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.
Here you can download the respective certificate:
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.
The text to be transmitted in the SMS is:
Hello Mr. Schubert, we would like to remind you of your appointment on January 20th 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 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.
The text to be transmitted in the SMS is:
Hello Mrs. Bartscher, your glasses are ready! Please pick them up from us soon. We look forward to seeing you! Until then, 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.
The text to be transmitted in the SMS is:
Hello Mrs. Bartscher, your glasses are ready! Please pick them up from us soon. We look forward to seeing you! Until then, 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.