Knowledge base

Getting started with MailerSend

Your go-to guide for settings up MailerSend and sending your first email with a test domain.

2. Confirm your email address from the verification email sent to the address you signed up with.

We'll then offer you a choice: start your free 14-day Professional trial by adding a payment method, giving you full access to send to real recipients and Professional features, or skip this and try Sandbox mode instead. If you choose to start the Professional trial, don't worry: we only use your payment method to verify it, and you won't be charged. Either way, you can send your first email right away using your test domain.

About your test domain: Use it to send up to 100 emails to 2 unique recipients, so you can see MailerSend in action before setting anything else up. This works the same whether you're in Sandbox mode or on the Professional trial. When you're ready to send to more people, add your own domain.

Modal to start a 14-day Professional trial with an option to skip to Sandbox mode instead

Step 2: Send your first email

You can send with the API or the SMTP relay. Not sure which one you need?

API: Best if you're building email sending into your own app or code
SMTP relay: Best if you're using a platform, CMS or plugin that asks for SMTP credentials, like WordPress

Still not sure? See the difference between the API and SMTP relay.

Option A: Send via API

Create an API token

From the menu on the left, click Developer tools > API tokens.
Click Create new token.
Give your token a name, select which domain you would like to use it with (or select all), choose an expiration date and select its permissions. To send emails, choose Full access, or Custom access with Email set to Full access.
Click Generate token.
Copy or download your token and keep it somewhere safe. For security, we'll only show it once.

Send your first email with cURL

The quickest way to send your first email is with cURL. There's nothing to install, just paste this into your terminal:

curl -X POST https://api.mailersend.com/v1/email \
  -H "Content-Type: application/json" \
  -H "X-Requested-With: XMLHttpRequest" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "from": {
      "email": "hello@YOUR_TEST_DOMAIN",
      "name": "Your Name"
    },
    "to": [
      {
        "email": "you@example.com",
        "name": "Your Name"
      }
    ],
    "subject": "Hello from MailerSend!",
    "text": "You just sent your first email with MailerSend.",
    "html": "<p>You just sent your first email with MailerSend.</p>"
  }'

Before you send, replace these 3 values:

YOUR_API_TOKEN: The token you just created
From email: Make one up using your test domain, like hello@ followed by your test domain. It doesn’t need to be a real inbox. You’ll find your test domain on the Domains page
To email: An inbox you can check, like your own email address. Your test domain can send to up to 2 unique recipients

If everything's set up correctly, you'll get a 202 Accepted response and your email will be on its way. 🎉

Prefer an SDK?

Install the SDK for your language:

PHP

composer require mailersend/mailersend

Laravel

composer require mailersend/laravel-driver

Java

<dependency>
  <groupId>com.mailersend</groupId>
  <artifactId>java-sdk</artifactId>
  <version>1.5.0</version>
</dependency>

Node.js

npm install mailersend

go get github.com/mailersend/mailersend-go

Python

pip install mailersend

Ruby

gem install mailersend-ruby

Then copy the code snippet into your project and add your API token. The same From and To rules apply:

PHP

use MailerSend\MailerSend;
use MailerSend\Helpers\Builder\Recipient;
use MailerSend\Helpers\Builder\EmailParams;

$mailersend = new MailerSend();

$recipients = [
    new Recipient('your@client.com', 'Your Client'),
];

$emailParams = (new EmailParams())
    ->setFrom('your@domain.com')
    ->setFromName('Your Name')
    ->setRecipients($recipients)
    ->setSubject('Subject')
    ->setHtml('This is the HTML content')
    ->setText('This is the text content')
    ->setReplyTo('reply to')
    ->setReplyToName('reply to name');

$mailersend->email->send($emailParams);

Laravel

<?php

namespace App\Mail;

use Carbon\Carbon;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Attachment;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Arr;
use MailerSend\Helpers\Builder\Personalization;
use MailerSend\Helpers\Builder\Variable;
use MailerSend\LaravelDriver\MailerSendTrait;

class TestEmail extends Mailable
{
    use Queueable, SerializesModels, MailerSendTrait;

    public function __construct() {}

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Test Email',
        );
    }

    public function content(): Content
    {
        $to = Arr::get($this->to, '0.address');

        $this->mailersend(
            template_id: null,
            tags: ['tag'],
            personalization: [
                new Personalization($to, [
                    'var' => 'variable',
                    'number' => 123,
                    'object' => [
                        'key' => 'object-value'
                    ],
                    'objectCollection' => [
                        ['name' => 'John'],
                        ['name' => 'Patrick']
                    ],
                ])
            ],
            precedenceBulkHeader: true,
            sendAt: new Carbon('2022-01-28 11:53:20'),
        );

        return new Content(
            view: 'emails.test_html',
            text: 'emails.test_text'
        );
    }

    public function attachments(): array
    {
        return [
            Attachment::fromStorageDisk('public', 'example.png')
        ];
    }
}

Java

import com.mailersend.sdk.emails.Email;
import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.MailerSendResponse;
import com.mailersend.sdk.exceptions.MailerSendException;

public void sendEmail() {

    Email email = new Email();

    email.setFrom("name", "your email");
    email.addRecipient("name", "your@recipient.com");
    email.addRecipient("name 2", "your@recipient2.com");

    Recipient recipient = new Recipient("name", "your@recipient3.com");
    email.AddRecipient(recipient);

    email.setSubject("Email subject");
    email.setPlain("This is the text content");
    email.setHtml("<p>This is the HTML content</p>");

    MailerSend ms = new MailerSend();
    ms.setToken("Your API token");

    try {
        MailerSendResponse response = ms.emails().send(email);
        System.out.println(response.messageId);
    } catch (MailerSendException e) {
        e.printStackTrace();
    }
}

Node.js

import 'dotenv/config';
import { MailerSend, EmailParams, Sender, Recipient } from "mailersend";

const mailerSend = new MailerSend({
  apiKey: process.env.API_KEY,
});

const sentFrom = new Sender("you@yourdomain.com", "Your name");

const recipients = [
  new Recipient("your@client.com", "Your Client")
];

const emailParams = new EmailParams()
  .setFrom(sentFrom)
  .setTo(recipients)
  .setReplyTo(sentFrom)
  .setSubject("This is a Subject")
  .setHtml("<strong>This is the HTML content</strong>")
  .setText("This is the text content");

await mailerSend.email.send(emailParams);

package main

import (
    "context"
    "os"
    "fmt"
    "time"

    "github.com/mailersend/mailersend-go"
)

func main() {
    ms := mailersend.NewMailersend(os.Getenv("MAILERSEND_API_KEY"))

    ctx := context.Background()
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    subject := "Subject"
    text := "This is the text content"
    html := "<p>This is the HTML content</p>"

    from := mailersend.From{
        Name:  "Your Name",
        Email: "your@domain.com",
    }

    recipients := []mailersend.Recipient{
        {
            Name:  "Your Client",
            Email: "your@client.com",
        },
    }

    sendAt := time.Now().Add(time.Minute * 5).Unix()
    tags := []string{"foo", "bar"}

    message := ms.Email.NewMessage()
    message.SetFrom(from)
    message.SetRecipients(recipients)
    message.SetSubject(subject)
    message.SetHTML(html)
    message.SetText(text)
    message.SetTags(tags)
    message.SetSendAt(sendAt)
    message.SetInReplyTo("client-id")

    res, _ := ms.Email.Send(ctx, message)
    fmt.Printf(res.Header.Get("X-Message-Id"))
}

Python

from mailersend import MailerSendClient, EmailBuilder

ms = MailerSendClient()

email = (EmailBuilder()
         .from_email("sender@domain.com", "Your Name")
         .to_many([{"email": "recipient@domain.com", "name": "Recipient"}])
         .subject("Hello from MailerSend!")
         .html("<h1>Hello World!</h1>")
         .text("Hello World!")
         .build())

response = ms.emails.send(email)

Ruby

require "mailersend-ruby"

ms_client = Mailersend::Client.new('your_mailersend_token')

ms_email = Mailersend::Email.new(ms_client)

ms_email.add_recipients("email" => "ron@parksandrec.com", "name" => "Ron")
ms_email.add_recipients("email" => "leslie@parksandrec.com", "name" => "Leslie")
ms_email.add_from("email" => "april@parksandrec.com", "name" => "April")
ms_email.add_subject("Time")
ms_email.add_text("Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.")
ms_email.add_html("<b>Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.</b>")

ms_email.send

Option B: Send with the SMTP relay

Create an SMTP user

From the menu on the left, click Email > Domains
Click your test domain
Click the Generate new user button to the right of the SMTP heading
Enter a name for your SMTP user.
Click Generate user.
Your SMTP credentials will be generated. Copy or download your password and keep it somewhere safe. For security, we'll only show it once.

Add your SMTP details

Add these details to your app, platform or plugin:

SMTP server: smtp.mailersend.net
Port: 587 or 2525
Username: Your SMTP username
Password: Your SMTP password
Encryption: TLS or STARTTLS, if you're asked to choose

Setup guides for popular tools

Remember:

Most SMTP plugins work the same way, so you can use whichever one you prefer. Just make sure it's from a trusted source to keep your credentials secure.

You can configure your Laravel app to use MailerSend SMTP relay by configuring the mailer with your SMTP credentials. First, use a basic mail command to build an email template, including the from, to, CC, BCC and content, then configure the mailer. For a standard SSL/TLS server, your configuration will look something like this:

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailersend.net
MAIL_PORT=587
MAIL_USERNAME=your_smtp_username
MAIL_PASSWORD=your_smtp_password
MAIL_ENCRYPTION=tls

You can configure PHPMailer to use MailerSend SMTP relay. Replace the SMTP credentials in the code snippet with your own to test.

<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;
require 'vendor/autoload.php'; 
$mail = new PHPMailer(true);
try {
    $mail->isSMTP();                                            
    $mail->Host       = 'smtp.mailersend.net';                     
    $mail->SMTPAuth   = true;                                   
    $mail->Username   = 'your_smtp_username';               
    $mail->Password   = 'your_smtp_password';                       
    $mail->SMTPSecure = 'tls'; 
    $mail->Port       = 587;
$mail->setFrom('from@example.com', 'From Name');
$mail->addAddress('recipient@example.com', 'Recipient Name');
$mail->isHTML(true); // Set email format to HTML
$mail->Subject = 'Your Subject Here';
$mail->Body    = '<b>This is the HTML message body</b>';
if(!$mail->send()){
    echo 'Message failed. Mailer Error: ' . $mail->ErrorInfo;
} else {
    echo 'Message has been sent';
}

If you want to use SMTP to integrate email sending into your Node.js apps, you can use the Nodemailer package. The following snippet configures MailerSend's SMTP relay and sends an email (remember to add your SMTP credentials).

First, add your SMTP credentials to your project's .env file:

SMTP_HOST=smtp.mailersend.net
SMTP_PORT=587
SMTP_USER=your_mailersend_username
SMTP_PASS=your_mailersend_password

Then use the following code snippet to send the email:

import 'dotenv/config';
import nodemailer from 'nodemailer';
// Load environment variables from .env file
import dotenv from 'dotenv';
dotenv.config();
// Create a transporter object using SMTP transport
const transporter = nodemailer.createTransport({
	host: process.env.SMTP_HOST,
	port: process.env.SMTP_PORT,
	secure: false, // true for 465, false for other ports
	auth: {
		user: process.env.SMTP_USER,
		pass: process.env.SMTP_PASS,
	},
});
// Setup email data
const mailOptions = {
	from: '"Name" <from@example.com>', // sender address
	to: 'recipient@example.com', // list of receivers
	subject: 'This is a test.', // Subject line
	text: 'Hey there! You just sent your first email with MailerSend. Nice one!', // plain text body
	html: `
    <p>Hey there!</p>
    <p>You just sent your first email with MailerSend.</p>
    <p>Nice one!</p>
  `, // html body
};
// Send email
transporter.sendMail(mailOptions, (error, info) => {
	if (error) {
		return console.log(error);
	}
	console.log('Message sent: %s', info.messageId);
});

Note:

Using WP Mail SMTP or the MailerSend plugin for WooCommerce? These plugins connect with an API token instead of SMTP credentials, so create a token by following the instructions in option A first.

Step 3: Check your email activity

Once you've sent your email, you can check your inbox to see if it's arrived as well as the Emails page.

To view the email's activity status, go to Email > Emails.

From here, you'll be able to see every point of a message's journey, from queued and sent to delivered, bounced, clicked and more. You should also see your email land in the inbox you sent it to. 🎉

Not seeing your email? Check your spam folder, and make sure the From address is on your test domain. If the status shows an error, see how to fix common sending issues.

Next steps: Take it live

Add a domain

When you're ready to start sending to recipients, the first step is to add your domain:

1. In the dashboard, scroll to the Start sending transactional emails section and click Add domain.

The Add domain option on the Getting Started page in MailerSend.

2. Click the Add domain button and follow the steps to authenticate your domain. With automatic domain connect, it only takes a few minutes.

Learn more:

Add your sending domain

→

How to add and authenticate your sending domain for secure sending.

Sending domains

→

Everything you need to know about managing your domains.

Get approved

The account approval process is a crucial step for accessing all MailerSend features. This involves providing details about your company or organization and explaining how you plan to use MailerSend. The more information you provide, the quicker you'll gain full access to all features.

To submit your account for approval, just click Get approved from the banner in the dashboard.

Get approved button on MailerSend dashboard

The approval process is usually very quick but can take up to 48 hours. We recommend you to provide clear, detailed information in your approval requests to help speed up this process. Rest assured, we'll notify you as soon as a decision is made.

Choose your plan

Whether you're on the Professional trial or in Sandbox mode, you can subscribe to a paid plan anytime by clicking Upgrade at the top of your dashboard. If you're still in Sandbox mode and want to try before you commit, click Start 14-day trial in the banner instead, that's a separate button from Upgrade and won't charge you.

To subscribe directly:

Click Upgrade at the top of your dashboard.
Select a plan and follow the steps to confirm. Choosing this path subscribes and charges you right away, so it's best if you're ready to commit.