Email API

Scheduled messages

Keep track of scheduled messages using MailerSend's Scheduled Messages API endpoint. Retrieve and delete scheduled messages with ease.

Use the GET request to retrieve information about scheduled messages. Scheduled messages are stored and queued until the Unix timestamp is reached. Please note that this timestamp is a minimal guarantee and that the email could be delayed due to server load.

Get list of scheduled messages

Get information on scheduled messages, such as subject, time of creation, and time of sending, with this GET request:

GET  https://api.mailersend.com/v1/message-schedules

Request parameters

JSON parameters are provided in dot notation

URL parameter	Type	Required	Limitations	Details
`domain_id`	`string`	no
`status`	`string`	no		Statuses: `scheduled`, `sent`, `error`
`page`	`int`	no
`limit`	`int`	no	Min: `10`, Max: `100`	Default: `25`

use MailerSend\MailerSend;
use \MailerSend\Common\Constants;

$mailersend = new MailerSend();

$mailersend->scheduleMessages->getAll(
    'domain_id',
    Constants::STATUS_SCHEDULED,
    $page = 3,
    $limit = 100
)

import 'dotenv/config';
import { MailerSend} from "mailersend";

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

mailerSend.email.schedule.list()
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

from mailersend import MailerSendClient, SchedulesBuilder

ms = MailerSendClient()

request = (SchedulesBuilder()
          .domain_id("domain-id")
          .build_list_request())

response = ms.schedules.list_schedules(request)

package main

import (
	"context"
	"log"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.TODO()

	domainID := "domain-id"

	_, _, err := ms.ScheduleMessage.List(ctx, domainID)
	if err != nil {
		log.Fatal(err)
	}
}

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.scheduledmessages.ScheduledMessagesList;
import com.mailersend.sdk.scheduledmessages.ScheduledMessage;

public void getScheduledMessages() {
    
    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {
    
        ScheduledMessagesList messages = ms.scheduledmessages().getScheduledMessages();

        for (ScheduledMessage message : messages.scheduledMessages) {
            System.out.println(message.id);
            System.out.println(message.subject);
        }

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

require "mailersend-ruby"

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

ms_scheduled_messages = Mailersend::ScheduledMessages.new(ms_client)
ms_scheduled_messages.get_list

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": [
    {
      "message_id": "61e01c6a7f97913a17075262",
      "subject": "Hello from Company",
      "send_at": "2022-01-01T12:00:00.000000Z",
      "status": "scheduled",
      "status_message": null,
      "created_at": "2022-01-17:00:00.000000Z"
    },
    ...
  ]
}

Error

Response Code: 422 Unprocessable Entity

See - Validation errors

Get a single scheduled message

Get information about a specific scheduled message, like its subject, creation date, sending date and domain, with this GET request:

GET https://api.mailersend.com/v1/message-schedules/{message_id}

Request parameters

URL parameter	Type	Required	Limitations	Details
`message_id`	string	yes		Message ID from the Send an email's response headers or Get scheduled messages response.

use MailerSend\MailerSend;

$mailersend = new MailerSend();

$mailersend->scheduleMessages->find('message_id');

import 'dotenv/config';
import { MailerSend} from "mailersend";

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

mailerSend.email.schedule.single("message_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

from mailersend import MailerSendClient, SchedulesBuilder

ms = MailerSendClient()

request = (SchedulesBuilder()
          .message_id("scheduled-id")
          .build_get_request())

response = ms.schedules.get_schedule(request)

package main

import (
	"context"
	"log"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.TODO()
	
	messageID := "message-id"

	_, _, err := ms.ScheduleMessage.Get(ctx, messageID)
	if err != nil {
		log.Fatal(err)
	}
}

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.scheduledmessages.ScheduledMessage;

public void getScheduledMessage() {
    
    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {
    
        ScheduledMessage message = ms.scheduledmessages().getScheduledMessage("message id");

        System.out.println(message.id);
        System.out.println(message.subject);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

require "mailersend-ruby"

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

ms_scheduled_messages = Mailersend::ScheduledMessages.new(ms_client)
ms_scheduled_messages.get_single(message_id: 'mess11454')

Responses

Valid

Response Code: 200 OK
Response Headers:
	content-type: application/json

{
  "data": {
    "message_id": "61e01f471053b349a5478a52",
    "subject": "Hello from Company",
    "send_at": "2022-01-01T12:00:00.000000Z",
    "status": "scheduled",
    "status_message": null,
    "created_at": "2022-01-01T17:00:00.000000Z",
    "domain": {
      "id": "7z3m5jgrogdpyo6n",
      "name": "mailersend.com",
      "created_at": "2022-01-01T12:00:00.000000Z",
      "updated_at": "2022-01-01T12:00:00.000000Z"
    },
    "message": {
      "id": "61e01f471053b349a5478a52",
      "created_at": "2022-01-01T12:00:00.000000Z",
      "updated_at": "2022-01-01T12:00:00.000000Z"
    }
  }
}

Error

Response Code: 404 Not Found

See - Validation errors

Delete a scheduled message

Delete a scheduled message with this DELETE request:

DELETE  https://api.mailersend.com/v1/message-schedules/{message_id}

Request parameters

URL parameter	Type	Required	Limitations	Details
`message_id`	string	yes	A scheduled message can be deleted up to 10 minutes before the sending time.

use MailerSend\MailerSend;
use \MailerSend\Common\Constants;

$mailersend = new MailerSend();

$mailersend->scheduleMessages->delete('message_id');

import 'dotenv/config';
import { MailerSend} from "mailersend";

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

mailerSend.email.schedule.delete("message_id")
  .then((response) => console.log(response.body))
  .catch((error) => console.log(error.body));

from mailersend import MailerSendClient, SchedulesBuilder

ms = MailerSendClient()

request = (SchedulesBuilder()
          .message_id("scheduled-id")
          .build_delete_request())

response = ms.schedules.delete_schedule(request)

package main

import (
	"context"
	"log"
	
	"github.com/mailersend/mailersend-go"
)

var APIKey = "Api Key Here"

func main() {
	// Create an instance of the mailersend client
	ms := mailersend.NewMailersend(APIKey)

	ctx := context.TODO()

	messageID := "message-id"
	
	_, err := ms.ScheduleMessage.Delete(ctx, messageID)
	if err != nil {
		log.Fatal(err)
	}
}

import com.mailersend.sdk.MailerSend;
import com.mailersend.sdk.exceptions.MailerSendException;
import com.mailersend.sdk.scheduledmessages.ScheduledMessage;

public void deleteScheduledMessage() {
    
    MailerSend ms = new MailerSend();

    ms.setToken("Your API token");

    try {
    
        boolean result = ms.scheduledmessages().deleteScheduledMessage("message id");

        System.out.println(result);

    } catch (MailerSendException e) {

        e.printStackTrace();
    }
}

require "mailersend-ruby"

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

ms_scheduled_messages = Mailersend::ScheduledMessages.new(ms_client)
ms_scheduled_messages.delete(message_id: 'mess11454')

Responses

Valid

Response Code: 204 OK
Response Body: [EMPTY]

Error

Response Code: 404 Not Found

Messages

Retrieve information about a single email or list of emails with the Messages API endpoint and optimize your processes.

Recipients

Manage your email recipients with ease using MailerSend's Recipients API. Get, create, update recipients and more with a simple API call. Learn more.

On this page

Get list of scheduled messages Responses Valid Error Get a single scheduled message Responses Valid Error Delete a scheduled message Responses Valid Error