openapi: 3.1.0
info:
  title: Transactional
  version: 2.0.0
  description: |
    Send transactional emails for order confirmations, password resets, notifications, and other user-triggered communications.
  contact:
    name: Mailtrap Support
    url: 'https://docs.mailtrap.io'
    email: support@mailtrap.io
  license:
    name: Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
    url: 'https://creativecommons.org/licenses/by-sa/4.0/'
  x-logo:
    url: 'https://mailtrap.io/wp-content/uploads/2021/04/mailtrap-logo.svg'

servers:
  - description: |
      Transactional Stream. Use a normal HTTP client `User-Agent` (as typical browsers and `curl` do); bare
      requests without one may be blocked by edge protection.
    url: 'https://send.api.mailtrap.io'

security:
  - HeaderAuth: []
  - BearerAuth: []

tags:
  - name: send-email
    x-page-title: Transactional
    x-page-description: Send individual transactional emails
    description: |
      Send transactional emails for order confirmations, password resets, and notifications.

      {% hint style="success" %}
      Best for: Real-time, one-to-one emails triggered by user actions
      {% endhint %}

paths:
  /api/send:
    post:
      summary: Send transactional email
      description: |
        Send a single transactional email with text, HTML, or template content.

        Use this endpoint for:
        - Order confirmations
        - Password reset emails
        - Account notifications
        - Welcome emails
        - System alerts
      operationId: sendEmail
      tags:
        - send-email
      x-codeSamples:
        - lang: shell
          label: 'cURL'
          source: |
            curl -X POST https://send.api.mailtrap.io/api/send \
              -H 'Authorization: Bearer YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "from": {"email": "sender@example.com"},
                "to": [{"email": "recipient@example.com"}],
                "subject": "Hello from Mailtrap",
                "text": "Welcome to Mailtrap!"
              }'
        - lang: javascript
          label: Node.js
          source: |
            import { MailtrapClient } from "mailtrap";

            const client = new MailtrapClient({
              token: process.env.MAILTRAP_API_KEY,
            });

            async function sendEmail() {
              await client.send({
                from: {
                  email: "sender@example.com",
                  name: "Sender Name"
                },
                to: [{ email: "recipient@example.com" }],
                subject: "Hello from Mailtrap",
                text: "Welcome to Mailtrap!",
                html: "<h1>Welcome to Mailtrap!</h1>"
              });
            }

            sendEmail();
        - lang: php
          label: PHP
          source: |
            <?php
            use Mailtrap\Helper\ResponseHelper;
            use Mailtrap\MailtrapClient;
            use Mailtrap\Mime\MailtrapEmail;
            use Symfony\Component\Mime\Address;

            $mailtrap = MailtrapClient::initSendingEmails(
                apiKey: $_ENV['MAILTRAP_API_KEY']
            );

            $email = (new MailtrapEmail())
                ->from(new Address('sender@example.com', 'Sender Name'))
                ->to(new Address('recipient@example.com'))
                ->subject('Hello from Mailtrap')
                ->text('Welcome to Mailtrap!')
                ->html('<h1>Welcome to Mailtrap!</h1>');

            $response = $mailtrap->send($email);
            var_dump(ResponseHelper::toArray($response));
        - lang: python
          label: Python
          source: |
            import mailtrap as mt

            client = mt.MailtrapClient(token="YOUR_API_KEY")

            mail = mt.Mail(
                sender=mt.Address(email="sender@example.com"),
                to=[mt.Address(email="recipient@example.com")],
                subject="Hello from Mailtrap",
                text="Welcome to Mailtrap!",
                html="<h1>Welcome to Mailtrap!</h1>"
            )

            client.send(mail)
        - lang: ruby
          label: Ruby
          source: |
            require 'mailtrap'

            client = Mailtrap::Client.new(api_key: 'YOUR_API_KEY')

            mail = Mailtrap::Mail.from_content(
              from: { email: 'sender@example.com' },
              to: [{ email: 'recipient@example.com' }],
              subject: 'Hello from Mailtrap',
              text: 'Welcome to Mailtrap!',
              html: '<h1>Welcome to Mailtrap!</h1>'
            )

            client.send(mail)
        - lang: csharp
          label: .NET
          source: |
            using Mailtrap;
            using Mailtrap.Emails.Requests;

            using var mailtrapFactory = new MailtrapClientFactory("YOUR_API_KEY");
            var client = mailtrapFactory.CreateClient();

            var email = SendEmailRequest.Create()
                .From("sender@example.com")
                .To("recipient@example.com")
                .Subject("Hello from Mailtrap")
                .Text("Welcome to Mailtrap!")
                .Html("<h1>Welcome to Mailtrap!</h1>");

            await client.Email().Send(email);
        - lang: java
          label: Java
          source: |
            import io.mailtrap.config.MailtrapConfig;
            import io.mailtrap.factory.MailtrapClientFactory;
            import io.mailtrap.model.Address;
            import io.mailtrap.model.MailtrapMail;
            import java.util.List;

            var config = new MailtrapConfig.Builder()
                .token("YOUR_API_KEY")
                .build();

            var client = MailtrapClientFactory.createMailtrapClient(config);

            var mail = MailtrapMail.builder()
                .from(new Address("sender@example.com", "Sender Name"))
                .to(List.of(new Address("recipient@example.com")))
                .subject("Hello from Mailtrap")
                .text("Welcome to Mailtrap!")
                .html("<h1>Welcome to Mailtrap!</h1>")
                .build();

            client.sendingApi().emails().send(mail);
        - lang: go
          label: Go
          source: |
            package main

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

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

            func main() {
            	client, err := mailtrap.NewClient(os.Getenv("MAILTRAP_API_TOKEN"))
            	if err != nil {
            		log.Fatal(err)
            	}

            	// The default client targets the transactional host.
            	response, _, err := client.Send(context.Background(), &mailtrap.SendRequest{
            		From:     mailtrap.Address{Email: "sender@mail.example.com", Name: "Mailtrap Test"},
            		To:       []mailtrap.Address{{Email: "recipient@example.com"}},
            		Subject:  "You are awesome!",
            		Text:     "Congrats for sending test email with Mailtrap!",
            		Category: "Integration Test",
            	})
            	if err != nil {
            		log.Fatal(err)
            	}

            	fmt.Printf("sent: %v\n", response.MessageIDs)
            }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/EmailWithText'
                - $ref: '#/components/schemas/EmailWithHtml'
                - $ref: '#/components/schemas/EmailWithTextAndHtml'
                - $ref: '#/components/schemas/EmailFromTemplate'
      responses:
        '200':
          description: Email successfully sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SentResponse'
              example:
                success: true
                message_ids:
                  - "0c7fd939-02cf-11ed-88c2-0a58a9feac02"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/batch:
    post:
      summary: Batch send emails
      description: |
        Send up to 500 transactional emails in a single API call. Each email can have unique recipients and content while sharing base properties.

        **Limits:**
        - Maximum 500 messages per call
        - Maximum 50 MB total payload size (including attachments)

        **Note:** The endpoint returns HTTP 200 even if individual messages fail. Check the `responses` array for individual message status.
      operationId: batchSendEmail
      tags:
        - send-email
      x-codeSamples:
        - lang: shell
          label: 'cURL'
          source: |
            curl -X POST https://send.api.mailtrap.io/api/batch \
              -H 'Authorization: Bearer YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "base": {
                  "from": {"email": "sender@example.com"},
                  "subject": "Monthly Newsletter"
                },
                "requests": [
                  {"to": [{"email": "user1@example.com"}]},
                  {"to": [{"email": "user2@example.com"}]},
                  {"to": [{"email": "user3@example.com"}]}
                ]
              }'
        - lang: javascript
          label: Node.js
          source: |
            import { MailtrapClient } from "mailtrap";

            const client = new MailtrapClient({
              token: process.env.MAILTRAP_API_KEY
            });

            async function sendBatch() {
              const response = await client.batchSend({
                base: {
                  from: { email: "sender@example.com" },
                  subject: "Important Update",
                  text: "Hello {{name}}, we have news for you."
                },
                requests: [
                  {
                    to: [{ email: "user1@example.com" }],
                    custom_variables: { name: "Alice" }
                  },
                  {
                    to: [{ email: "user2@example.com" }],
                    custom_variables: { name: "Bob" }
                  }
                ]
              });

              console.log("Batch sent:", response);
            }

            sendBatch();
        - lang: php
          label: PHP
          source: |
            <?php
            use Mailtrap\Helper\ResponseHelper;
            use Mailtrap\MailtrapClient;
            use Mailtrap\Mime\MailtrapEmail;
            use Symfony\Component\Mime\Address;

            $mailtrap = MailtrapClient::initSendingEmails(
                apiKey: $_ENV['MAILTRAP_API_KEY']
            );

            $baseEmail = (new MailtrapEmail())
                ->from(new Address('sender@example.com', 'Sender'))
                ->subject('Monthly Newsletter')
                ->text('Check out our latest updates!');

            $recipients = [
                (new MailtrapEmail())->to(new Address('user1@example.com', 'User 1')),
                (new MailtrapEmail())->to(new Address('user2@example.com', 'User 2'))
            ];

            $response = $mailtrap->batchSend($recipients, $baseEmail);

            var_dump(ResponseHelper::toArray($response));
        - lang: python
          label: Python
          source: |
            import mailtrap as mt

            client = mt.MailtrapClient(
                token="YOUR_API_KEY"
            )

            batch_mail = mt.BatchSendEmailParams(
                base=mt.BatchMail(
                    sender=mt.Address(email="sender@example.com"),
                    subject="Monthly Newsletter",
                    text="Check out our latest updates!"
                ),
                requests=[
                    mt.BatchEmailRequest(
                        to=[mt.Address(email="user1@example.com")]
                    ),
                    mt.BatchEmailRequest(
                        to=[mt.Address(email="user2@example.com")]
                    )
                ]
            )

            response = client.batch_send(batch_mail)
        - lang: ruby
          label: Ruby
          source: |
            require 'mailtrap'

            client = Mailtrap::Client.new(
              api_key: 'YOUR_API_KEY'
            )

            batch_base = Mailtrap::Mail.batch_base_from_content(
              from: { email: 'sender@example.com' },
              subject: 'Monthly Newsletter',
              text: 'Check out our latest updates!'
            )

            client.send_batch(
              batch_base,
              [
                Mailtrap::Mail.from_content(
                  to: [{ email: 'user1@example.com' }]
                ),
                Mailtrap::Mail.from_content(
                  to: [{ email: 'user2@example.com' }]
                )
              ]
            )
        - lang: csharp
          label: .NET
          source: |
            using Mailtrap;
            using Mailtrap.Configuration;
            using Mailtrap.Emails.Requests;

            var config = new MailtrapClientOptions
            {
                ApiToken = "YOUR_API_KEY"
            };

            using var mailtrapFactory = new MailtrapClientFactory(config);
            var client = mailtrapFactory.CreateClient();

            var batchRequest = BatchEmailRequest.Create()
                .Base(b => b
                    .From("sender@example.com")
                    .Subject("Monthly Newsletter")
                    .Text("Check out our latest updates!"))
                .Requests(r => r
                    .To("user1@example.com"))
                .Requests(r => r
                    .To("user2@example.com"));
            await client.BatchEmail().Send(batchRequest);
        - lang: java
          label: Java
          source: |
            import io.mailtrap.config.MailtrapConfig;
            import io.mailtrap.factory.MailtrapClientFactory;
            import io.mailtrap.model.request.emails.Address;
            import io.mailtrap.model.request.emails.BatchEmailBase;
            import io.mailtrap.model.request.emails.MailtrapBatchMail;
            import io.mailtrap.model.request.emails.MailtrapMail;
            import java.util.List;

            var config = new MailtrapConfig.Builder()
                .token("YOUR_API_KEY")
                .build();

            var client = MailtrapClientFactory.createMailtrapClient(config);

            var base = BatchEmailBase.builder()
                .from(new Address("sender@example.com"))
                .subject("Monthly Newsletter")
                .text("Check out our latest updates!")
                .build();

            var requests = List.of(
                MailtrapMail.builder()
                    .to(List.of(new Address("user1@example.com")))
                    .build(),
                MailtrapMail.builder()
                    .to(List.of(new Address("user2@example.com")))
                    .build()
            );

            var batchMail = MailtrapBatchMail.builder()
                .base(base)
                .requests(requests)
                .build();

            client.sendingApi().emails().batchSend(batchMail);
        - lang: go
          label: Go
          source: |
            package main

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

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

            func main() {
            	client, err := mailtrap.NewClient(os.Getenv("MAILTRAP_API_TOKEN"))
            	if err != nil {
            		log.Fatal(err)
            	}

            	// Base holds the fields shared by every message; per-request fields override it.
            	response, _, err := client.SendBatch(context.Background(), &mailtrap.BatchSendRequest{
            		Base: &mailtrap.SendRequest{
            			From:     mailtrap.Address{Email: "sender@mail.example.com", Name: "Mailtrap Test"},
            			Subject:  "You are awesome!",
            			Text:     "Congrats for sending test email with Mailtrap!",
            			Category: "Integration Test",
            		},
            		Requests: []mailtrap.SendRequest{
            			{To: []mailtrap.Address{{Email: "first@example.com"}}},
            			{To: []mailtrap.Address{{Email: "second@example.com"}}},
            		},
            	})
            	if err != nil {
            		log.Fatal(err)
            	}

            	for i, item := range response.Responses {
            		fmt.Printf("message %d: success=%t ids=%v errors=%v\n", i, item.Success, item.MessageIDs, item.Errors)
            	}
            }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEmail'
      responses:
        '200':
          description: Batch processed. Check individual responses for delivery status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  securitySchemes:
    HeaderAuth:
      type: apiKey
      description: API token in Api-Token header
      in: header
      name: Api-Token
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication

  schemas:
    Address:
      type: object
      properties:
        email:
          type: string
          format: email
          example: john@example.com
        name:
          type: string
          example: John Doe

    EmailSender:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/Address'

    EmailSenderRequired:
      type: object
      required:
        - from
      properties:
        from:
          $ref: '#/components/schemas/Address'

    EmailRecipients:
      type: object
      properties:
        to:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/Address'
        cc:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/Address'
        bcc:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/Address'

    EmailReplyTo:
      type: object
      properties:
        reply_to:
          $ref: '#/components/schemas/Address'

    EmailSubject:
      type: object
      properties:
        subject:
          type: string
          minLength: 1
          example: Your Order Confirmation

    EmailSubjectRequired:
      type: object
      required:
        - subject
      properties:
        subject:
          type: string
          minLength: 1
          example: Your Order Confirmation

    EmailText:
      type: object
      properties:
        text:
          type: string
          minLength: 1
          example: Thank you for your order!

    EmailTextRequired:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          minLength: 1
          example: Thank you for your order!

    EmailHtml:
      type: object
      properties:
        html:
          type: string
          minLength: 1
          example: <h1>Thank you for your order!</h1>

    EmailHtmlRequired:
      type: object
      required:
        - html
      properties:
        html:
          type: string
          minLength: 1
          example: <h1>Thank you for your order!</h1>

    EmailCategory:
      type: object
      properties:
        category:
          type: string
          maxLength: 255
          example: transactional

    EmailCustomVariables:
      type: object
      properties:
        custom_variables:
          type: object
          additionalProperties:
            type: string
          example:
            user_id: "12345"
            order_id: "ORD-789"

    EmailSendingHeaders:
      type: object
      properties:
        headers:
          type: object
          additionalProperties:
            type: string
          example:
            X-Message-Source: api.example.com
            X-Campaign-ID: CAMP-123

    EmailAttachments:
      type: object
      properties:
        attachments:
          type: array
          items:
            type: object
            required:
              - content
              - filename
            properties:
              content:
                type: string
                description: Base64 encoded content
                example: base64encodedcontent==
              filename:
                type: string
                example: document.pdf
              type:
                type: string
                description: MIME type
                example: application/pdf
              disposition:
                type: string
                enum: [attachment, inline]
                default: attachment
              content_id:
                type: string
                description: For inline attachments
                example: image001

    TemplateUuid:
      type: object
      properties:
        template_uuid:
          type: string
          format: uuid
          description: Email template UUID
          example: b81aabcd-1a1e-41cf-91b6-eca0254b3d96

    TemplateUuidRequired:
      type: object
      required:
        - template_uuid
      properties:
        template_uuid:
          type: string
          format: uuid
          description: Email template UUID
          example: b81aabcd-1a1e-41cf-91b6-eca0254b3d96

    TemplateVariables:
      type: object
      properties:
        template_variables:
          type: object
          description: Template variable values
          example:
            user_name: John Doe
            order_number: "12345"

    EmailWithText:
      title: Text Only
      allOf:
        - $ref: '#/components/schemas/EmailSenderRequired'
        - $ref: '#/components/schemas/EmailRecipients'
        - $ref: '#/components/schemas/EmailReplyTo'
        - $ref: '#/components/schemas/EmailSubjectRequired'
        - $ref: '#/components/schemas/EmailTextRequired'
        - $ref: '#/components/schemas/EmailAttachments'
        - $ref: '#/components/schemas/EmailSendingHeaders'
        - $ref: '#/components/schemas/EmailCustomVariables'
        - $ref: '#/components/schemas/EmailCategory'

    EmailWithHtml:
      title: HTML Only
      allOf:
        - $ref: '#/components/schemas/EmailSenderRequired'
        - $ref: '#/components/schemas/EmailRecipients'
        - $ref: '#/components/schemas/EmailReplyTo'
        - $ref: '#/components/schemas/EmailSubjectRequired'
        - $ref: '#/components/schemas/EmailHtmlRequired'
        - $ref: '#/components/schemas/EmailAttachments'
        - $ref: '#/components/schemas/EmailSendingHeaders'
        - $ref: '#/components/schemas/EmailCustomVariables'
        - $ref: '#/components/schemas/EmailCategory'

    EmailWithTextAndHtml:
      title: Text and HTML
      allOf:
        - $ref: '#/components/schemas/EmailSenderRequired'
        - $ref: '#/components/schemas/EmailRecipients'
        - $ref: '#/components/schemas/EmailReplyTo'
        - $ref: '#/components/schemas/EmailSubjectRequired'
        - $ref: '#/components/schemas/EmailTextRequired'
        - $ref: '#/components/schemas/EmailHtmlRequired'
        - $ref: '#/components/schemas/EmailAttachments'
        - $ref: '#/components/schemas/EmailSendingHeaders'
        - $ref: '#/components/schemas/EmailCustomVariables'
        - $ref: '#/components/schemas/EmailCategory'

    EmailFromTemplate:
      title: From Template
      allOf:
        - $ref: '#/components/schemas/EmailSenderRequired'
        - $ref: '#/components/schemas/EmailRecipients'
        - $ref: '#/components/schemas/EmailReplyTo'
        - $ref: '#/components/schemas/TemplateUuidRequired'
        - $ref: '#/components/schemas/TemplateVariables'
        - $ref: '#/components/schemas/EmailAttachments'
        - $ref: '#/components/schemas/EmailSendingHeaders'
        - $ref: '#/components/schemas/EmailCustomVariables'

    SentResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message_ids:
          type: array
          description: Message IDs (one per recipient)
          items:
            type: string
            example: 0c7fd939-02cf-11ed-88c2-0a58a9feac02

    SendEmailErrorResponse:
      type: object
      description: |
        Error responses from the sending API use `success: false` and an `errors` array of strings
        (unlike account APIs on `mailtrap.io`, which use `error` or a single `errors` string).
      properties:
        success:
          type: boolean
          example: false
        errors:
          type: array
          items:
            type: string
            example: Invalid sender email address
      example:
        success: false
        errors:
          - "'from' address is invalid"

    BatchEmail:
      title: Batch Email Request
      description: Send multiple emails in a single API call (up to 500)
      type: object
      required:
        - requests
      properties:
        base:
          description: Base properties shared by all emails
          allOf:
            - $ref: '#/components/schemas/EmailSender'
            - $ref: '#/components/schemas/EmailReplyTo'
            - $ref: '#/components/schemas/EmailSubject'
            - $ref: '#/components/schemas/EmailText'
            - $ref: '#/components/schemas/EmailHtml'
            - $ref: '#/components/schemas/EmailAttachments'
            - $ref: '#/components/schemas/EmailSendingHeaders'
            - $ref: '#/components/schemas/EmailCategory'
            - $ref: '#/components/schemas/EmailCustomVariables'
            - $ref: '#/components/schemas/TemplateUuid'
            - $ref: '#/components/schemas/TemplateVariables'
        requests:
          type: array
          description: Individual email configurations (max 500)
          maxItems: 500
          items:
            allOf:
              - $ref: '#/components/schemas/EmailSender'
              - $ref: '#/components/schemas/EmailRecipients'
              - $ref: '#/components/schemas/EmailReplyTo'
              - $ref: '#/components/schemas/EmailSubject'
              - $ref: '#/components/schemas/EmailText'
              - $ref: '#/components/schemas/EmailHtml'
              - $ref: '#/components/schemas/EmailAttachments'
              - $ref: '#/components/schemas/EmailSendingHeaders'
              - $ref: '#/components/schemas/EmailCategory'
              - $ref: '#/components/schemas/EmailCustomVariables'
              - $ref: '#/components/schemas/TemplateUuid'
              - $ref: '#/components/schemas/TemplateVariables'
      
    BatchSentResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Overall request success
          example: true
        responses:
          type: array
          description: Individual message results
          items:
            type: object
            properties:
              success:
                type: boolean
                example: true
              message_ids:
                type: array
                items:
                  type: string
                  example: 0c7fd939-02cf-11ed-88c2-0a58a9feac02
              errors:
                type: array
                items:
                  type: string
        errors:
          type: array
          description: General errors
          items:
            type: string

  responses:
    BadRequest:
      description: Bad request. Fix errors listed in response before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendEmailErrorResponse'
          example:
            success: false
            errors:
              - "'from' is required"
              - "'to', 'cc' or 'bcc' address is required"
              - "'subject' is required"
              - must specify either text or html body

    Unauthorized:
      description: Unauthorized. Check your API credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendEmailErrorResponse'
          example:
            success: false
            errors:
              - Unauthorized

    Forbidden:
      description: Forbidden. Verify domain or check permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendEmailErrorResponse'
          example:
            success: false
            errors:
              - Forbidden

    InternalError:
      description: Internal server error. Retry later or contact support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendEmailErrorResponse'
          example:
            success: false
            errors:
              - Internal server error