Hello World!

# Sending an Email (/api/v1/email)


This endpoint allows you to start sending emails through the MailerSend Email API.

## Send an email [#send-an-email]

This endpoint allows you to send an asynchronous email. It returns the status of the email sent with an `x-message-id` that can be used to continuously query for the status using the Email API.

Send an email using this `POST` request:

```http
POST https://api.mailersend.com/v1/email
```

#### Request Body \[!toc] [#request-body-toc]

<Tabs items="['JSON', 'PHP', 'NodeJS', 'Python', 'Go', 'Java', 'Ruby']">
  <Tab value="JSON">
    ```json
    {
        "from": {
          "email": "hello@mailersend.com",
          "name": "MailerSend"
        },
        "to": [
          {
            "email": "john@mailersend.com",
            "name": "John Mailer"
          }
        ],
        "subject": "Hello from {{company}}!",
        "text": "This is just a friendly hello from your friends at {{company}}.",
        "html": "<b>This is just a friendly hello from your friends at {{company}}.</b>",
        "personalization": [
          {
            "email": "john@mailersend.com",
            "data": {
              "company": "MailerSend"
            }
          }
        ]
      }
    ```
  </Tab>

  <Tab value="PHP">
    ```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);
    ```

    [More examples](https://github.com/mailersend/mailersend-php)
  </Tab>

  <Tab value="NodeJS">
    ```javascript
    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);
    ```

    [More examples](https://github.com/mailersend/mailersend-nodejs)
  </Tab>

  <Tab value="Python">
    ```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)
    print(f"Email sent: {response.message_id}")
    ```

    [More examples](https://github.com/mailersend/mailersend-python)
  </Tab>

  <Tab value="Go">
    ```go
    package main

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

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

    func main() {
    	// Create an instance of the mailersend client
    	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",
    		},
    	}

    	// Send in 5 minute
    	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"))

    }
    ```

    [More examples](https://github.com/mailersend/mailersend-go)
  </Tab>

  <Tab value="Java">
    ```java
    import com.mailersend.sdk.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");

        // you can also add multiple recipients by calling addRecipient again
        email.addRecipient("name 2", "your@recipient2.com");

        // there's also a recipient object you can use
        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();
        }
    }
    ```

    [More examples](https://github.com/mailersend/mailersend-java)
  </Tab>

  <Tab value="Ruby">
    ```ruby
    require "mailersend-ruby"

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

    # Intialize the email class
    ms_email = Mailersend::Email.new(ms_client)

    # Add parameters
    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>")

    # Send the email
    ms_email.send
    ```

    [More examples](https://github.com/mailersend/mailersend-ruby)
  </Tab>
</Tabs>

#### Request parameters \[!toc] [#request-parameters-toc]

*JSON parameters are provided in dot notation*

| JSON parameter              | Type              | Required | Limitations                                                                                      | Details                                                                                                                                                                                                                     |
| --------------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`                      | `object`          | yes \*   |                                                                                                  | Not required if `template_id` is present and template has default sender set.                                                                                                                                               |
| `from.email`                | `string`          | yes \*   | Must be a verified domain or a subdomain from a verified domain .                                | Not required if `template_id` is present and template has default sender set. Valid email address as per RFC 2821.                                                                                                          |
| `from.name`                 | `string`          | no       |                                                                                                  | `from.email` will be used if not provided or, if `template_id` is present with default values, the default subject from that will be used.                                                                                  |
| `to`                        | `object[]`        | yes      | Min `1`, max `50`                                                                                |                                                                                                                                                                                                                             |
| `to.*.email`                | `string`          | yes      |                                                                                                  | Valid email address as per RFC 2821.                                                                                                                                                                                        |
| `to.*.name`                 | `string`          | no       |                                                                                                  | The name of the recipient. May not contain `;` or `,`.                                                                                                                                                                      |
| `cc`                        | `object[]`        | no       | Max 10                                                                                           |                                                                                                                                                                                                                             |
| `cc.*.email`                | `string`          | yes      |                                                                                                  | Valid email address as per RFC 2821.                                                                                                                                                                                        |
| `cc.*.name`                 | `string`          | no       |                                                                                                  | The name of the CC recipient. May not contain `;` or `,`.                                                                                                                                                                   |
| `bcc`                       | `object[]`        | no       | Max 10                                                                                           |                                                                                                                                                                                                                             |
| `bcc.*.email`               | `string`          | yes      |                                                                                                  | Valid email address as per RFC 2821.                                                                                                                                                                                        |
| `bcc.*.name`                | `string`          | no       |                                                                                                  | The name of the BCC recipient. May not contain `;` or `,`.                                                                                                                                                                  |
| `reply_to`                  | `object`          | no       |                                                                                                  |                                                                                                                                                                                                                             |
| `reply_to.email`            | `string`          | no       |                                                                                                  | Valid email address as per RFC 2821.                                                                                                                                                                                        |
| `reply_to.name`             | `string`          | no       |                                                                                                  |                                                                                                                                                                                                                             |
| `subject`                   | `string`          | yes \*   | Max 998                                                                                          | Not required if `template_id` is present and template has default subject set.                                                                                                                                              |
| `text`                      | `string`          | yes \*   | Max size of 2 MB.                                                                                | Email represented in a text (`text/plain`) format. \* Only required if there's no `html` or `template_id` present.                                                                                                          |
| `html`                      | `string`          | yes \*   | Max size of 2 MB.                                                                                | Email represented in HTML (`text/html`) format. \* Only required if there's no `text` or `template_id` present.                                                                                                             |
| `attachments`               | `object[]`        | no       |                                                                                                  |                                                                                                                                                                                                                             |
| `attachments.*.content`     | `string`          | yes      | Max size of 25MB. *After decoding Base64*                                                        | Base64 encoded content of the attachment.                                                                                                                                                                                   |
| `attachments.*.disposition` | `string`          | no       | Must be one of the attachment types: `inline`, `attachment`                                      | Use `inline` to make it accessible for content. use `attachment` to normal attachments                                                                                                                                      |
| `attachments.*.filename`    | `string`          | yes      |                                                                                                  |                                                                                                                                                                                                                             |
| `attachments.*.id`          | `string`          | no       | Max: `256`                                                                                       | Can be used in content as `<img src="cid:*"/>`. Must also set `attachments.*.disposition` as `inline`.                                                                                                                      |
| `template_id`               | `string`          | yes \*   |                                                                                                  | \* Only required if there's no `text` or `html` present.                                                                                                                                                                    |
| `tags`                      | `string[]`        | no       |                                                                                                  | Limit is max 5 tags. If the template used already has tags, then the request will override them.                                                                                                                            |
| `tags.*`                    | `string`          | no       | Max 191 characters                                                                               |                                                                                                                                                                                                                             |
| `personalization`           | `object[]`        | no       |                                                                                                  | Allows using personalization in `{{var}}` syntax. Can be used in the `subject`, `html`, `text` fields. Read more about [advanced personalization](/api/v1/email/features#advanced-personalization).                         |
| `personalization.*.email`   | `string`          | yes      |                                                                                                  | Email address that personalization will be applied to. Valid email address as per RFC 2821.                                                                                                                                 |
| `personalization.*.data`    | `object[]`        | yes      |                                                                                                  | Object with `key: value` pairs. Values will be added to your template using `{{key}}` syntax.                                                                                                                               |
| `precedence_bulk`           | `boolean`         | no       |                                                                                                  | This parameter will override domain's advanced settings                                                                                                                                                                     |
| `send_at`                   | `integer\|string` | no       | min: `now`, max: `now + 72hours`                                                                 | Unix timestamp (integer) or ISO 8601 date string. &#x2A;*Please note that this timestamp is a minimal guarantee and that the email could be delayed due to server load.**                                                   |
| `in_reply_to`               | `string`          | no       | Max 998 characters. Valid characters: alphanumeric and `_ . @ = < > ( ~ ! # $ % ^ & * + ) - [ ]` | A Message-ID that this email is replying to. &#x2A;*Please note that this feature is available to paid plan accounts only.**                                                                                                |
| `references`                | `string[]`        | no       |                                                                                                  | List of Message-ID's that the current email is referencing. Read more about [creating email threads](/../../guides/creating-email-threads). &#x2A;*Please note that this feature is available to paid plan accounts only.** |
| `references.*`              | `string`          | yes      | Valid characters: alphanumeric and `_ . @ = < > ( ~ ! # $ % ^ & * + ) - [ ]`                     |                                                                                                                                                                                                                             |
| `settings`                  | `object`          | no       |                                                                                                  |                                                                                                                                                                                                                             |
| `settings.*`                | `boolean`         | yes      |                                                                                                  | Can only contain the keys: `track_clicks`, `track_opens` and `track_content` and a boolean value of `true` or `false`.                                                                                                      |
| `headers`                   | `object[]`        | no       |                                                                                                  | **Please note that this feature is available to Professional and Enterprise accounts only**                                                                                                                                 |
| `headers.*.name`            | `string`          | yes      | Must be alphanumeric which can contain `-`                                                       |                                                                                                                                                                                                                             |
| `headers.*.value`           | `string`          | yes      |                                                                                                  |                                                                                                                                                                                                                             |
| `list_unsubscribe`          | `string`          | no       | Accepts a single value that complies with RFC 8058. Max 990 characters.                          | **Please note that this feature is available to Professional and Enterprise accounts only**                                                                                                                                 |

#### Supported file types [#supported-file-types]

| File type           | Extensions                                                                     |
| ------------------- | ------------------------------------------------------------------------------ |
| Text files          | .txt, .csv, .log, .css, .ics .xml                                              |
| Image files         | .jpg, .jpe, .jpeg, .gif, .png, .bmp, .psd, .tif, .tiff, .svg, .indd, .ai, .eps |
| Document files      | .doc, .docx, .rtf, .odt, .ott, .pdf, .pub, .pages, .mobi, .epub                |
| Audio files         | .mp3, .m4a, .m4v, .wma, .ogg, .flac, .wav, .aif, .aifc, .aiff                  |
| Video files         | .mp4, .mov, .avi, .mkv, .mpeg, .mpg, .wmv                                      |
| Spreadsheet files   | .xls, .xlsx, .ods, .numbers                                                    |
| Presentation files  | .odp, .ppt, .pptx, .pps, .key                                                  |
| Archive files       | .zip, .vcf                                                                     |
| Email files         | .eml                                                                           |
| Cryptographic files | .p7c, .p7m, .p7s, .pgp, .asc, .sig                                             |

#### Supported HTML tags and attributes in personalization data [#supported-html-tags-and-attributes-in-personalization-data]

We allow limited HTML in personalization data to enhance content formatting. Only the following tags and attributes are supported,  unsupported elements will be removed for security reasons.

| Category          | Supported                                                                                                          |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| Container tags    | `p` `b` `i` `strong` `em` `a` `li` `ul` `q` `blockquote` `abbr` `address` `cite` `bdo` `strike` `u` `h1` `h2` `h3` |
| Self-closing tags | `br` `img`                                                                                                         |
| Attributes        | `id` `class` `style` `href` `src` `width` `height` `alt` `lang` `title` `dir` `cite` `target`                      |

<Callout type="warn" title="Note">
  If a scheduled email is sent with a template, and that template is deleted before the sending is triggered, the scheduled email will not be sent.
</Callout>

### Responses [#responses]

#### Sending queued [#sending-queued]

```http
Response Code: 202 Accepted
Response Headers:
	content-type: text/plain; charset=utf-8
	x-message-id: 5e42957d51f1d94a1070a733
Response Body: [EMPTY]
```

#### Sending paused [#sending-paused]

```http
Response Code: 202 Accepted
Response Headers:
	content-type: text/plain; charset=utf-8
	x-message-id: 5e42957d51f1d94a1070a733
  x-send-paused: true
Response Body: [EMPTY]
```

#### Validation error [#validation-error]

```http
Response Code: 422 Unprocessable Entity
Response Headers:
	content-type: application/json
```

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "from.email": [
      "The from.email domain must be verified in your account to send emails. #MS42207"
    ]
  }
}
```

*See - [Validation errors](/../../general#validation-errors)*

#### Validation warning — some suppressed [#validation-warning--some-suppressed]

```http
Response Code: 202 Accepted
Response Headers:
	content-type: application/json
	x-message-id: 5e42957d51f1d94a1070a733
```

```json
{
  "message": "There are some warnings for your request.",
  "warnings": [
  	{
  		"type": "SOME_SUPPRESSED",
        "warning": "Some of the recipients have been suppressed.",
  		"recipients": [
    		{
      		"email": "suppressed@recipient.com",
      		"name": "Suppressed Recipient",
      		"reasons": ["blocklisted"]
    		}
  		]
  	}
  ]
}
```

#### Validation warning — all suppressed [#validation-warning--all-suppressed]

When all recipients are suppressed, the email is not sent and no `x-message-id` header is returned.

```http
Response Code: 202 Accepted
Response Headers:
	content-type: application/json
```

```json
{
  "message": "There are some warnings for your request.",
  "warnings": [
    {
      "type": "ALL_SUPPRESSED",
      "message": "All of the recipients provided have been suppressed.",
      "recipients": [
        {
          "email": "suppressed@recipient.com",
          "name": "Suppressed Recipient",
          "reasons": ["blocklisted"]
        }
      ]
    }
  ]
}
```

### Send encrypted emails [#send-encrypted-emails]

You can use MailerSend to send encrypted messages using S/MIME or PGP. The sender encrypts messages that use these protocols. Their contents can only be viewed by recipients with the private keys required to decrypt the messages.

MailerSend supports the following MIME types, which you can use to send S/MIME encrypted emails:

```
application/pkcs7-mime
application/pkcs7-signature
application/x-pkcs7-mime
application/x-pkcs7-signature
```

MailerSend also supports the following MIME types, which you can use to send PGP-encrypted emails:

```
application/pgp-encrypted
application/pgp-keys
application/pgp-signature
```

## Send bulk emails [#send-bulk-emails]

This endpoint allows you to send multiple asynchronous emails. It returns the status of the request sent with a `bulk_email_id` that can be used to continuously query for the status using the Email API.

To prevent long waiting periods for a response, each email validation is done after the request and then the result is stored. If there is any validation error, you can query it using the `bulk_email_id` provided.

Send a bulk email using this `POST` request:

```http
POST https://api.mailersend.com/v1/bulk-email
```

#### Request Body \[!toc] [#request-body-toc-1]

<Tabs items="['JSON', 'PHP', 'NodeJS', 'Python', 'Go', 'Java', 'Ruby']">
  <Tab value="JSON">
    ```json
    [
        {
          "from": {
            "email": "hello@mailersend.com",
            "name": "MailerSend"
          },
          "to": [
            {
              "email": "john@mailersend.com",
              "name": "John Mailer"
            }
          ],
          "subject": "Hello from {{company}}!",
          "text": "This is just a friendly hello from your friends at {{company}}.",
          "html": "<b>This is just a friendly hello from your friends at {{company}}.</b>",
          "personalization": [
            {
              "email": "john@mailersend.com",
              "data": {
                "company": "MailerSend"
              }
            }
          ]
        },
        {
          "from": {
            "email": "hello@mailersend.com",
            "name": "MailerSend"
          },
          "to": [
            {
              "email": "jane@mailersend.com",
              "name": "Jane Mailer"
            }
          ],
          "subject": "Welcome to {{company}}!",
          "text": "This is a welcoming message from your friends at {{company}}.",
          "html": "<b>This is a welcoming message from your friends at {{company}}.</b>",
          "personalization": [
            {
              "email": "jane@mailersend.com",
              "data": {
                "company": "MailerSend"
              }
            }
          ]
        }
      ]
    ```
  </Tab>

  <Tab value="PHP">
    ```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'),
    ];

    $bulkEmailParams = [];

    $bulkEmailParams[] = (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');

    $bulkEmailParams[] = (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');

    $mailersend->bulkEmail->send($bulkEmailParams);
    ```

    [More examples](https://github.com/mailersend/mailersend-php)
  </Tab>

  <Tab value="NodeJS">
    ```javascript
    import 'dotenv/config';
    import { MailerSend, EmailParams, Sender, Recipient } from "mailersend";

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

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

    const bulkEmails = [];

    const emailParams = new EmailParams()
      .setFrom(sentFrom)
      .setTo([
        new Recipient("your@client.com", "Your Client")
      ])
      .setSubject("This is a Subject")
      .setHtml("<strong>This is the HTML content</strong>")
      .setText("This is the text content");

    bulkEmails.push(emailParams);

    const emailParams2 = new EmailParams()
      .setFrom(sentFrom)
      .setTo([
        new Recipient("your_2@client.com", "Your Client 2")
      ])
      .setSubject("This is a Subject 2")
      .setHtml("<strong>This is the HTML content 2</strong>")
      .setText("This is the text content 2");

    bulkEmails.push(emailParams2);

    await mailerSend.email.sendBulk(bulkEmails);
    ```

    [More examples](https://github.com/mailersend/mailersend-nodejs)
  </Tab>

  <Tab value="Python">
    ```python
    from mailersend import MailerSendClient, EmailBuilder

    ms = MailerSendClient()

    # Create individual EmailRequest objects
    emails = [
        EmailBuilder()
            .from_email("sender@domain.com", "Sender")
            .to_many([{"email": "recipient1@domain.com", "name": "Recipient 1"}])
            .subject("Bulk email 1")
            .html("<h1>Hello from bulk email 1</h1>")
            .text("Hello from bulk email 1")
            .build(),
        EmailBuilder()
            .from_email("sender@domain.com", "Sender")
            .to_many([{"email": "recipient2@domain.com", "name": "Recipient 2"}])
            .subject("Bulk email 2")
            .html("<h1>Hello from bulk email 2</h1>")
            .text("Hello from bulk email 2")
            .build()
    ]

    response = ms.emails.send_bulk(emails)
    print(f"Bulk email ID: {response.bulk_email_id}")
    ```

    [More examples](https://github.com/mailersend/mailersend-python)
  </Tab>

  <Tab value="Go">
    ```go
    package main

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

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

    func main() {
    	// Create an instance of the mailersend client
    	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",
    		},
    	}

    	var messages []*mailersend.Message
    	
    	for i := range [2]int{} {
    		msg := &mailersend.Message{
    			From:       from,
    			Recipients: recipients,
    			Subject:    fmt.Sprintf("%s %v", subject, i),
    			Text:       text,
    			HTML:       html,
    		}
    		messages = append(messages, msg)
    	}
    	
    	_, _, err := ms.BulkEmail.Send(ctx, messages)
    	if err != nil {
    		log.Fatal(err)
    	}

    }
    ```

    [More examples](https://github.com/mailersend/mailersend-go)
  </Tab>

  <Tab value="Java">
    ```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 sendBulkEmails() {

        Email email1 = new Email();

        email1.setFrom("name", "your email");
        email1.addRecipient("name", "your@first-recipient.com");
       
        email1.setSubject("Email subject 1");

        email1.setPlain("This is the text content for the first email");
        email1.setHtml("<p>This is the HTML content for the first email</p>");

        Email email2 = new Email();

        email2.setFrom("name", "your email");
        email2.addRecipient("name", "your@second-recipient.com");
       
        email2.setSubject("Email subject 2");

        email2.setPlain("This is the text content for the second email");
        email2.setHtml("<p>This is the HTML content for the second email</p>");

        MailerSend ms = new MailerSend();

        ms.setToken("Your API token");

        try {
        
            String bulkSendId = ms.emails().bulkSend(new Email[] { email1, email2 });

            // you can use the bulkSendId to get the status of the emails
            System.out.println(bulkSendId);

        } catch (MailerSendException e) {

            e.printStackTrace();
        }
    }
    ```

    [More examples](https://github.com/mailersend/mailersend-java)
  </Tab>

  <Tab value="Ruby">
    ```ruby
    require "mailersend-ruby"

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

    ms_bulk_email = Mailersend::BulkEmail.new(ms_client)

    ms_bulk_email.messages = [
        {
            'from' => {"email" => "april@parksandrec.com", "name" => "April"},
            'to' => [{"email" => "ron@parksandrec.com", "name" => "Ron"}],
            'subject' => "Time",
            'text' => "Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.",
            'html' => "<b>Time is money, money is power, power is pizza, and pizza is knowledge. Let's go.</b>",
          },
          {
            'from' => {"email" => "april@parksandrec.com", "name" => "April"},
            'to' => [{"email" => "leslie@parksandrec.com", "name" => "Leslie"}],
            'subject' => "Lorem Ipsum",
            'text' => "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
            'html' => "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>",
          }
    ]

    ms_bulk_email.send
    ```

    [More examples](https://github.com/mailersend/mailersend-ruby)
  </Tab>
</Tabs>

#### Request parameters \[!toc] [#request-parameters-toc-1]

*JSON parameters are provided in dot notation*

| JSON parameter | Type       | Required | Limitations                                      | Details                                                                  |
| -------------- | ---------- | -------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| `*`            | `object[]` | yes      | Must be an array.                                | Array of email objects.                                                  |
| `*.*`          | `object`   | yes      | Must be an [email](/email#send-an-email) object. | See [email](/email#send-an-email) object for detailed options available. |

#### Limitations [#limitations]

| Description                                            | Limit                                                                                                                                                                  |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Total size of the JSON payload                         | **50MB**                                                                                                                                                               |
| Number of individual email objects in a single request | **5** for Trial plan accounts.<br />**500** for Hobby, Starter, Professional or Enterprise plan accounts.                                                              |
| Number of recipients per email object.                 | See &#x2A;*[Email endpoint](/email#send-an-email)**.                                                                                                                   |
| API requests per minute                                | **10** for Trial and Hobby plan accounts.<br />**15** for Starter plan accounts.<br />**30** for Professional plan accounts.<br />**60** for Enterprise plan accounts. |

*If not mentioned, the limits are the same as for the generic Email API endpoint.*

### Responses [#responses-1]

```http
Response Code: 202 Accepted
Response Headers:
    content-type: application/json
```

```json
{
  "message": "The bulk email is being processed.",
  "bulk_email_id": "614470d1588b866d0454f3e2"
}
```

### Errors [#errors]

#### Validation errors [#validation-errors]

Validation errors, as well as any other issues like failed emails, are stored in the database. You can check them by calling the 'Get bulk email' endpoint.

Validation errors are indexed by the order they are sent: `message.{order_index}`.

#### Suppression errors [#suppression-errors]

If one or more recipients specified in the messages are suppressed, similarly to the validation errors, they are stored and can be checked with the 'Get bulk email' endpoint.

The suppression errors are indexed by `x-message-id`.

## Get bulk email status [#get-bulk-email-status]

Get the bulk email information like validation errors, failed emails and more.

Check the bulk email status using this `GET` request:

```http
GET https://api.mailersend.com/v1/bulk-email/{bulk_email_id}
```

#### Request parameters \[!toc] [#request-parameters-toc-2]

| URL parameter   | Type     | Required | Limitations | Details |
| --------------- | -------- | -------- | ----------- | ------- |
| `bulk_email_id` | `string` | yes      |             |         |

<Tabs items="['PHP', 'NodeJS', 'Python', 'Go', 'Java', 'Ruby']">
  <Tab value="PHP">
    ```php
    use MailerSend\MailerSend;

    $mailersend = new MailerSend();

    $mailersend->bulkEmail->getStatus('bulk_email_id');
    ```

    [More examples](https://github.com/mailersend/mailersend-php)
  </Tab>

  <Tab value="NodeJS">
    ```javascript
    import 'dotenv/config';
    import { MailerSend } from "mailersend";

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

    mailerSend.email.getBulkStatus('bulk_email_id') // bulk email Id e.g 63af1fdb790d97105a090001
      .then((response) => {
        console.log(response.body);
      });
    ```

    [More examples](https://github.com/mailersend/mailersend-nodejs)
  </Tab>

  <Tab value="Python">
    ```python
    from mailersend import MailerSendClient

    ms = MailerSendClient()

    response = ms.emails.get_bulk_status("bulk-email-id")
    print(f"Status: {response.state}")
    ```

    [More examples](https://github.com/mailersend/mailersend-python)
  </Tab>

  <Tab value="Go">
    ```go
    package main

    import (
    	"context"
    	"time"
    	"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.Background()
    	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    	defer cancel()
    	
    	_, _, err := ms.BulkEmail.Status(ctx, "bulk-email-id")
    	if err != nil {
    		log.Fatal(err)
    	}
    	
    }
    ```

    [More examples](https://github.com/mailersend/mailersend-go)
  </Tab>

  <Tab value="Java">
    ```java
    import com.mailersend.sdk.emails.Email;
    import com.mailersend.sdk.emails.BulkSendStatus;
    import com.mailersend.sdk.MailerSend;
    import com.mailersend.sdk.MailerSendResponse;
    import com.mailersend.sdk.exceptions.MailerSendException;

    public void getBulkEmailsStatus() {

        MailerSend ms = new MailerSend();

        ms.setToken("Your API token");

        try {
        
            BulkSendStatus status = ms.emails().bulkSendStatus("bulk send id");

            System.out.println(status.state);

        } catch (MailerSendException e) {

            e.printStackTrace();
        }
    }
    ```

    [More examples](https://github.com/mailersend/mailersend-java)
  </Tab>

  <Tab value="Ruby">
    ```ruby
    require "mailersend-ruby"

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

    ms_bulk_email = Mailersend::BulkEmail.new(ms_client)
    ms_bulk_email.get_bulk_status(bulk_email_id: 'yourbulkemailid')
    ```

    [More examples](https://github.com/mailersend/mailersend-ruby)
  </Tab>
</Tabs>

### Responses [#responses-2]

#### Valid [#valid]

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

```json
{
  "data": {
    "id": "614470d1588b866d0454f3e2",
    "state": "completed",
    "total_recipients_count": 1,
    "suppressed_recipients_count": 0,
    "suppressed_recipients": null,
    "validation_errors_count": 0,
    "validation_errors": null,
    "messages_id": "['61487a14608b1d0b4d506633']",
    "created_at": "2021-09-17T10:41:21.892000Z",
    "updated_at": "2021-09-17T10:41:23.684000Z"
  }
}
```

#### Invalid [#invalid]

```http
Response Code: 404 Not Found
```