Skip to content

Sending e-mail

Estimated time to read: 4 minutes

In order to start sending email, you will need to authenticate to our service. For this, you will use an SMTP or API Sending Credential. Within the App dashboard, you can create as many Sending Credentials as you like. Once you've added a credential, you'll have a unique SMTP username and password or API token which you can use to authenticate against our service.

Read on to create your first Sending Credential.

Prerequisites

  • Transactional Email Service Account
  • Access to the App Dashboard

Creating Sending Credentials

Create your Sending Credentials on the Credentials Tab within the App dashboard.

  1. Choose to create SMTP or API Key v2 credentials
  2. Provide a descriptive name that will be shown to you in the dashboard so that you can identify this credential later.
  3. Choose the mode this Sending Credential should operate in: Production or Sandbox mode. Click here to find out more about Sandbox mode.
  4. Choose the Scope for these credentials: Global or Scoped to specific domains. Click here to find out more about Scoped Credentials.

Modifying credentials

From to the Credentials Tab, click on any credential to modify its basic settings, including the mode it operates in and the domains it is allowed to send from.

For comprehensive API key management, access the advanced settings through your user menu:

  1. Click your name in the top right corner
  2. Select API Keys from the dropdown menu
  3. Locate and select your specific API key

Here you can allow or deny access to individual endpoints, giving you precise control over what operations your API key can perform.

API reference

We have two API endpoints available: APIv2 and legacy v1. We recommend using APIv2.

The API Swagger Documentation for APIv2: https://api.simplemailservice.eu/api-docs-v2/

The API endpoint for APIv2 is: https://api.simplemailservice.eu/v2/

The legacy documentation for v1 can be found here.

Code examples

Curl example with API

Below is a Curl example. In this example we are sending one email with an attachment. Drop the element attachments if you do not want to attach any attachments.

Replace ACCOUNTID and APITOKEN.

curl -X 'POST' \
  'https://api.simplemailservice.eu/v2/accounts/ACCOUNTID/messages' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer APITOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": {
    "email": "noreply@janjansen.nl",
    "name": "Example Corp"
  },
  "recipients": [
    {
      "email": "John@janjansen.nl",
      "name": "John Doe"
    }
  ],
  "subject": "Welcome to Example Corp",
  "html_content": "<h1>Welcome {{ first_name }}!</h1>",
  "text_content": "Welcome {{ first_name }}!",
  "attachments":[
    {
      "data":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
      "base64":true,
      "content_type":"image\/svg+xml",
      "file_name":"logo.svg"
    }
  ],
  "substitutions": {
    "first_name": "John"
  }

}'

PHP example with SMTP

We advise using something like PHPMailer for sending emails using SMTP. Symfony Mailer is also a very good choice. We advise against using the default mail() function for sending emails with SMTP, as it is very basic and has limited functionality.

Within your project run:

composer require phpmailer/phpmailer

With the below script you will be able to send your first e-mail. In this example we define a Sender and Recipient, attachments and create the e-mail. For demonstration purposes we also add custom headers to configure data retention, click tracking and open tracking on an individual basis.

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php';

$mail = new PHPMailer(true);

try {
    //Server settings
    $mail->isSMTP();                                          // Set mailer to use SMTP
    $mail->Host       = 'send.simplemailservice.eu';                   // Specify main and backup SMTP servers
    $mail->SMTPAuth   = true;                                 // Enable SMTP authentication
    $mail->Username   = 'YOUR_SMTP_USERNAME';                 // SMTP username
    $mail->Password   = 'YOUR_SMTP_PASSWORD';                 // SMTP password
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;       // Enable TLS encryption, `ssl` also accepted
    $mail->Port       = 587;                                  // TCP port to connect to

    //Recipients
    $mail->setFrom('sender@example.com', 'Display Name');
    $mail->addAddress('recipient@example.com', 'Firstname Lastname');   // Add a recipient

    //Set custom headers
    $mail->addCustomHeader('seseu-track-clicks', 'false');
    $mail->addCustomHeader('seseu-track-opens', 'true');
    $mail->addCustomHeader('seseu-data-retention', '0');

    // Attachments
    $mail->addAttachment('/path/to/file.pdf');                // Add attachments
    $mail->addAttachment('/path/to/image.jpg', 'new.jpg');    // Optional name

    // Content
    $mail->isHTML(true);                                      // Set email format to HTML
    $mail->Subject = 'This is the subject';
    $mail->Body    = 'This is the HTML message body <i>in italics!</i>';
    $mail->AltBody = 'This is the body in plain text for non-HTML mail clients';

    $mail->send();
    echo 'Message has been sent';
} catch (Exception $e) {
    echo "Message could not be sent. Mailer Error: {$mail->ErrorInfo}";
}

Python example with SMTP

Python comes shipped with the Smtplib library which is a great library for creating advanced email messages.

Below is an advanced example. In this example we define a Sender and Recipient, attachments and create the e-mail. For demonstration purposes we also add custom headers to configure data retention, click tracking and open tracking on an individual basis.

import smtplib
from email.message import EmailMessage

def send_html_email_with_attachment():
    smtp_server = "send.simplemailservice.eu"
    smtp_port = 587
    smtp_username = "YOUR_SMTP_USERNAME"
    smtp_password = "YOUR_SMTP_PASSWORD"
    from_addr = "sender@example.com"
    to_addr = "recipient@example.com"
    subject = "This is the subject"

    # Create a MIME message
    msg = EmailMessage()
    msg['Subject'] = subject
    msg['From'] = from_addr
    msg['To'] = to_addr

    # Set custom headers
    msg.add_header("seseu-track-clicks", "false")
    msg.add_header("seseu-track-opens", "true")
    msg.add_header("seseu-data-retention", "0")

    msg.set_content('This is the plain text version of the email')

    # Attach the HTML part
    html_content = """\
    <html>
        <head></head>
        <body>
            This is the HTML message body <i>in italics!</i>
        </body>
    </html>
    """
    msg.add_alternative(html_content, subtype='html')

    # Attach a file
    filename = "path_to_your_attachment"
    with open(filename, "rb") as f:
        file_data = f.read()
        file_name = f.name
        msg.add_attachment(file_data, maintype='application', subtype='octet-stream', filename=file_name)

    # Connect to the SMTP server and send the email
    server = smtplib.SMTP(smtp_server, smtp_port)
    server.starttls()
    server.login(smtp_username, smtp_password)
    server.send_message(msg)
    server.quit()

send_html_email_with_attachment()