Mail API

The Mail API turns your emails into messages: you send a mail to the address of your configuration, we evaluate it based on your patterns and send the result as an SMS, RCS, WhatsApp, or voice message. Where the recipient, the text, and the sender appear in the mail is something you describe once in the configuration. Recipients can be phone numbers, contacts, or groups from your address book.

Fixed Address with Mail Patterns

Every Mail API configuration has a fixed, system-generated address and three patterns. The patterns describe what your mails look like: where the recipient is, where the message text is, and what else the mail contains. That way the Mail API adapts to your application. You create the configuration itself as described in the Setup section.

Structure of the Address

The address consists of a fixed token and an optional prefix in front of it:

TOKEN@gateway.seven.io
PREFIX.TOKEN@gateway.seven.io

TOKEN is generated by us, is fixed, and is shown in your login under Developer > API Access. PREFIX is yours to choose for each mail: everything before the last dot of the local part is the prefix and is evaluated with the pattern for the address prefix.

So in the address 441761234567890.a1b2c3d4e5f6g7h8@gateway.seven.io, a1b2c3d4e5f6g7h8 is the token and 441761234567890 is the prefix.

Short Address without Token

With the option Address without token enabled in the configuration (possible once the DMARC check is active, see Security), the token may be omitted: a mail to 441761234567890@gateway.seven.io is then assigned to the configuration by your sender address alone, and the whole local part of the address is the prefix. Only proven senders count here (see Security). If more than one configuration lists the same proven sender, none of them is used; a proven address takes precedence over a proven domain entry. The token address keeps working in any case.

Setup in Five Steps

The dialog under Developer > API Access guides you through the five steps of a configuration. You save in the last step, and only once a test mail from one of the allowed senders has arrived.

Variables

The following variables are available in the patterns. The list is exhaustive; there are no further variables.

Basic

Extended: {{delay}}, {{type}}, {{label}}, {{foreign_id}}, {{unicode}}, {{flash}}, {{performance_tracking}}, {{get_replies}}

The meaning and permitted values of these variables are described in the Classic Format section under Parameters and apply here unchanged. {{type}} overrides the type set in the configuration for the individual mail. {{get_replies}} takes yes or no: with yes we send the message from a number that can receive replies, so the recipient can answer directly; a sender you set is replaced by it.

WhatsApp: {{template}}, {{template_lang}}, {{header}}, {{body}}, {{buttons}}, {{media_url}}, {{media_type}}, {{caption}}

These variables fill the fields of a WhatsApp message; their meaning is described in the WhatsApp (WA) section.

Authentication is based on your sender address and the token in the address; there is no key.

Each variable may appear at most once across all three patterns. {{text}} must be captured by one of the patterns, {{to}} must either be captured or set via Fixed recipient.

How we evaluate the mail

• The pattern for the address prefix must cover the entire prefix.
• In subject and body we search for the pattern: the literal text must appear, the variables capture the text in between.
• An empty pattern means that this part of the mail is ignored.
• A captured sender ID takes precedence over Sender of the message, a captured recipient over Fixed recipient.
• If a pattern does not match the corresponding part of the mail, the message is not sent.

Security

Sender verification applies unchanged: we only accept mails from one of the sender addresses you have stored in the respective configuration, or from an address of a domain stored there (*@domain).

DMARC check

Once every sender of a configuration is proven, the DMARC check switches on for it automatically, the moment the last proof arrives; there is no switch to flip. We then only accept a mail if the sender domain (the domain of the From address) passes the DMARC check on our gateway. This requires a DMARC record for your domain together with SPF or DKIM; a domain without a DMARC record never passes. Forwarding is uncritical as long as the DKIM signature stays intact.

You prove a sender address by sending a test mail from it to the test address of the configuration that passes the DMARC check. You prove a domain entry (*@domain) with a TXT record seven-mail-api-verify=TOKEN on the domain; in addition the domain (or a parent domain) has to publish a DMARC record. We recheck both daily and revoke the proof once the TXT record has been missing for a few days. A configuration with an active DMARC check no longer accepts unproven senders; create a second configuration for senders without DMARC. The Address without token is a separate option that only becomes available with an active DMARC check; leave it off to combine token and DMARC. Domain entries are not possible for freemail domains, and a sender address proven in one account can no longer be stored in any other account.

A rejected mail shows up with code 904 in your Debugger. In this case an error mail goes exclusively to the stored error mail address and never to the sender of the mail, since that sender may be forged.

Examples

Default configuration

Without adjusting the patterns, the entire body becomes the message text. The recipient is set in the configuration and the mail goes to the bare address.

Result: an SMS to 441761234567890 with the text "Your parcel is on its way." The subject is ignored.

Recipient in the address

If every mail should go to a different phone number, capture the recipient with {{to}} in the prefix of the address. A fixed recipient is not needed then.

Result: an SMS to 441761234567890 with the text "Your parcel is on its way."

Alert in the subject, fixed recipient

A monitoring tool sends its alert in the subject to a fixed address. The recipient is set in the configuration.

Result: an SMS to 441761234567890 with the text "CPU load critical on srv-07".

Pattern with anchors

If the mail contains more than just the message text, delimit it with literal text. Here two pairs of parentheses enclose the text, followed by the dispatch time.

Result: an SMS to 441761234567890 with the text "Your order is on its way.", scheduled for 15 January 2027 at 08:00. The time in the example stands for any point in the future that your application sets itself.

Error Handling

If a pattern does not match the corresponding part of the mail or the recipient remains empty, the message is not sent. You receive an error mail stating the reason, provided you have activated the "Notify in case of errors" option. With the DMARC check active, the same applies to mails whose sender domain fails the DMARC check; that error mail only goes to the error mail address.

Setup

In your login under Developer > API Access, you manage your configurations. The Create New button at the top right and the Mail API tile create a new one; the dialog guides you through the five steps described above. You can create any number of configurations, each with its own allowed senders, its own fixed address, and its own patterns. Saving is only possible after a test mail from one of the allowed senders; after that the configuration can be used immediately.

The general settings for the Mail API are under Developer > Settings in the Mail API section.

Mail API Settings

• Maximum Character Count: Set a maximum character count to avoid overly long messages by sending signatures. Enter 0 to disable this function.
• Remove Signature: If this is activated, the API automatically tries to remove quoted text in the mail.
• Notification on 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, a pattern does not match your mail, or details such as the recipient are missing, we will send you an email with information about the error. When creating a configuration, you can optionally specify an alternative email address to which you would like to receive the error messages.
• HTTP Push on Error: If this is activated, we additionally report failed mails via HTTP to your webhooks, with error code and error description.
• Insert Sender in SMS: 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:

Classic Format

Configurations created before the fixed address was introduced work in the classic format: the recipient is part of the local part of the address, the parameters are in the subject. They are marked as Legacy in the dashboard and continue to work unchanged and without a time limit. New configurations use mail patterns.

Structure of the Mail

Mails to a legacy configuration have the structure described below. New configurations use the fixed address with mail patterns instead.

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:

WhatsApp (WA)

The Mail API also sends WhatsApp messages. In a configuration with mail patterns you set the type to WhatsApp and enter your WhatsApp Service Frontend ID (Format: WA-XXXXXXXX) as the sender of the message; in a legacy configuration you set type=WA and the from parameter. You can find the ID in your seven.io Dashboard under WABA → Services. The following fields are available in both cases: as variables in the patterns or as parameters in the subject.

WhatsApp Message Types

WhatsApp supports three message types, which are automatically determined based on the parameters:

if template != null:
    → Template message
else if media_url != null:
    → Media message
else:
    → Text message (email body)

Template Messages

Template messages are required for messages outside the 24h window and must be pre-approved by WhatsApp.

Media Messages

Media messages can only be sent within the 24h conversation window.

Text Messages

For simple text messages within the 24h window, the email body is used as the message.

WhatsApp Examples (Classic Format)

1. Template Message (outside 24h window)

To: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=order_confirmation.template_lang=de_DE.body=John,12345@gateway.seven.io

2. Template with Header Image

To: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=promo_image.header=https://example.com/promo.jpg.body=20%25-discount@gateway.seven.io

3. Text Message (within 24h window)

To: 491512345678.MYKEY.type=WA.from=WA-5AAB129C@gateway.seven.io

4. Send Image (within 24h window)

To: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=image.media_url=https://example.com/product.jpg.caption=Your-product@gateway.seven.io

5. Send Document

To: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=document.media_url=https://example.com/invoice.pdf.caption=Your-invoice@gateway.seven.io

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 specify the recipient and further details as in the classic format via parameters in the subject, 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.

Our gateway checks every incoming mail against SPF, DKIM, and DMARC. By default the result is informational only: what decides acceptance is the comparison with the stored sender addresses. Only once the DMARC check of your Mail API configuration is active (every sender proven) are mails rejected whose sender domain fails the DMARC check (code 904, see Security above). Rejected mails can be viewed in your Debugger.

Examples for the Classic Format

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:

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.

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.

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 a configuration with a fixed address and mail patterns to be able to use the full range of functions.