Send Transactional Email

POST

/v1/send/email

Production

Sends a transactional email using a custom from, subject, and html/text body.

Use this endpoint when you need full control over the email content. For template-based sends, use POST /v1/send/template instead.

Authorizations

Request Body^required

Request body for sending a transactional email.

Either html or text must be provided. Both are accepted simultaneously.

object

from

required

object

name

required

Sender display name

string

John Doe

email

required

Sender email address (must be an authorized sender in your account)

string format: email

john@doe.com

required

List of recipients

Array<object>

object

name

required

Recipient display name

string

Jane Smith

email

required

Recipient email address

string format: email

jane@smith.com

subject

required

Email subject line

string

Welcome to Our Service

text

required

Plain-text version of the email body

string

Hello, this is a test email.

html

required

HTML version of the email body

string

<p>Hello, this is a test email.</p>

variables

Dynamic variables to inject into the email content. Available from variable_a_var to variable_z_var.

Use them in your content with {{variable_a_var}} syntax.

object

variable_a_var

Use in dynamic content as {{variable_a_var}}

string

Variable A Value

attachment

Files to attach via URL. The server will download and attach each file. (Max size per file: 10MB)

Array<object>

object

name

required

File name as it will appear in the attachment

string

document.pdf

url

required

Publicly accessible URL of the file

string format: uri

https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf

attachment_buffer

Files to attach via base64-encoded content. (Max size per file: 10MB)

Array<object>

object

name

required

File name as it will appear in the attachment

string

document.pdf

content

required

Base64-encoded file content

string format: byte

data:(mime type),base64,JVBERi0xLjQKJazc...

Responses

201

Email successfully queued

object

status

boolean

true

message

string

Succesfully queued email

data

UUIDs assigned to each queued email, one per recipient

Array<string>

Example

{
  "status": true,
  "message": "Succesfully queued email",
  "data": [
    "1b9d6e34-634a-4762-8d5a-f9cb9165d432"
  ]
}

401

Unauthorized — invalid or missing API token

object

status

boolean

message

string

An http error occurred. If error persists, contact soporte@contacta.mx

data

object

message

string

code

integer

Example

{
  "status": false,
  "message": "An http error occurred. If error persists, contact soporte@contacta.mx",
  "data": {
    "message": "Your key auth is not valid, please check with your administrator",
    "code": 401
  }
}

402

Insufficient credits to complete the send

object

status

boolean

message

string

An http error occurred. If error persists, contact soporte@contacta.mx

data

object

message

string

code

integer

Example

{
  "status": false,
  "message": "An http error occurred. If error persists, contact soporte@contacta.mx",
  "data": {
    "message": "Not enough credits for make this send, please check and retry",
    "code": 402
  }
}

422

Unprocessable entity — validation failed on request body

object

status

boolean

message

string

An http error occurred. If error persists, contact soporte@contacta.mx

data

object

message

string

code

integer

Example

{
  "status": false,
  "message": "An http error occurred. If error persists, contact soporte@contacta.mx",
  "data": {
    "message": "Missing required fields, please verify your request",
    "code": 422
  }
}

451

One or more recipients are blacklisted (unsubscribed)

object

status

boolean

message

string

An http error occurred. If error persists, contact soporte@contacta.mx

data

object

message

string

code

integer

Example

{
  "status": false,
  "message": "An http error occurred. If error persists, contact soporte@contacta.mx",
  "data": {
    "message": "One or more email addresses are blacklisted for unsubscribing, please check.",
    "code": 451
  }
}

Examples

Useful for guiding users to view code examples in different developer languages.

curl -X POST "https://api.example.com/v1/send/email" \
    -H "Accept: application/json" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{"from":{"name":"John Doe","email":"john@doe.com"},"to":[{"name":"Jane Smith","email":"jane@smith.com"}],"subject":"Welcome to Our Service","text":"Hello, this is a test email.","html":"<p>Hello, this is a test email.</p>","variables":{"variable_a_var":"Variable A Value"},"attachment":[{"name":"document.pdf","url":"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf"}],"attachment_buffer":[{"name":"document.pdf","content":"data:(mime type),base64,JVBERi0xLjQKJazc..."}]}'

  const fetch = require('node-fetch');

  fetch("https://api.example.com/v1/send/email", {
    method: "POST",
    headers: {
  "Accept": "application/json",
  "Connection": "keep-alive",
  "Content-Type": "application/json",
  "Authorization": "Bearer <your-token>"
},
    body: JSON.stringify({
  "from": {
    "name": "John Doe",
    "email": "john@doe.com"
  },
  "to": [
    {
      "name": "Jane Smith",
      "email": "jane@smith.com"
    }
  ],
  "subject": "Welcome to Our Service",
  "text": "Hello, this is a test email.",
  "html": "<p>Hello, this is a test email.</p>",
  "variables": {
    "variable_a_var": "Variable A Value"
  },
  "attachment": [
    {
      "name": "document.pdf",
      "url": "https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf"
    }
  ],
  "attachment_buffer": [
    {
      "name": "document.pdf",
      "content": "data:(mime type),base64,JVBERi0xLjQKJazc..."
    }
  ]
})
  })
    .then(res => res.json())
    .then(console.log)
    .catch(console.error);

  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.example.com/v1/send/email",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Connection: keep-alive",
    "Content-Type: application/json",
    "Authorization: Bearer <your-token>"
    ],
    CURLOPT_POSTFIELDS => json_encode({
  "from": {
    "name": "John Doe",
    "email": "john@doe.com"
  },
  "to": [
    {
      "name": "Jane Smith",
      "email": "jane@smith.com"
    }
  ],
  "subject": "Welcome to Our Service",
  "text": "Hello, this is a test email.",
  "html": "<p>Hello, this is a test email.</p>",
  "variables": {
    "variable_a_var": "Variable A Value"
  },
  "attachment": [
    {
      "name": "document.pdf",
      "url": "https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf"
    }
  ],
  "attachment_buffer": [
    {
      "name": "document.pdf",
      "content": "data:(mime type),base64,JVBERi0xLjQKJazc..."
    }
  ]
})
  ]);

  $response = curl_exec($curl);
  curl_close($curl);
  echo $response;
  ?>

  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  var client = new HttpClient();
  var request = new HttpRequestMessage(HttpMethod.POST, "https://api.example.com/v1/send/email") {
    Content = new StringContent("{
  \"from\": {
    \"name\": \"John Doe\",
    \"email\": \"john@doe.com\"
  },
  \"to\": [
    {
      \"name\": \"Jane Smith\",
      \"email\": \"jane@smith.com\"
    }
  ],
  \"subject\": \"Welcome to Our Service\",
  \"text\": \"Hello, this is a test email.\",
  \"html\": \"<p>Hello, this is a test email.</p>\",
  \"variables\": {
    \"variable_a_var\": \"Variable A Value\"
  },
  \"attachment\": [
    {
      \"name\": \"document.pdf\",
      \"url\": \"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf\"
    }
  ],
  \"attachment_buffer\": [
    {
      \"name\": \"document.pdf\",
      \"content\": \"data:(mime type),base64,JVBERi0xLjQKJazc...\"
    }
  ]
}", Encoding.UTF8, "application/json")
  };
  request.Headers.Add("Accept", "application/json");
request.Headers.Add("Connection", "keep-alive");
request.Headers.Add("Content-Type", "application/json");
request.Headers.Add("Authorization", "Bearer <your-token>");
  var response = await client.SendAsync(request);
  var responseBody = await response.Content.ReadAsStringAsync();
  Console.WriteLine(responseBody);

  import requests
  import json

  url = "https://api.example.com/v1/send/email"
  headers = {
    "Accept": "application/json",
  "Connection": "keep-alive",
  "Content-Type": "application/json",
  "Authorization": "Bearer <your-token>"
  }
  data = {
  "from": {
    "name": "John Doe",
    "email": "john@doe.com"
  },
  "to": [
    {
      "name": "Jane Smith",
      "email": "jane@smith.com"
    }
  ],
  "subject": "Welcome to Our Service",
  "text": "Hello, this is a test email.",
  "html": "<p>Hello, this is a test email.</p>",
  "variables": {
    "variable_a_var": "Variable A Value"
  },
  "attachment": [
    {
      "name": "document.pdf",
      "url": "https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf"
    }
  ],
  "attachment_buffer": [
    {
      "name": "document.pdf",
      "content": "data:(mime type),base64,JVBERi0xLjQKJazc..."
    }
  ]
}

  response = requests.post(url, headers=headers, json=data)
  print(response.text)

  import java.io.OutputStream;
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.nio.charset.StandardCharsets;

  public class ApiExample {
    public static void main(String[] args) throws Exception {
      URL url = new URL("https://api.example.com/v1/send/email");
      HttpURLConnection conn = (HttpURLConnection) url.openConnection();
      conn.setRequestMethod("POST");
      conn.setDoOutput(true);
      conn.setRequestProperty("Accept", "application/json");
    conn.setRequestProperty("Connection", "keep-alive");
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setRequestProperty("Authorization", "Bearer <your-token>");

      String jsonInputString = "{\"from\":{\"name\":\"John Doe\",\"email\":\"john@doe.com\"},\"to\":[{\"name\":\"Jane Smith\",\"email\":\"jane@smith.com\"}],\"subject\":\"Welcome to Our Service\",\"text\":\"Hello, this is a test email.\",\"html\":\"<p>Hello, this is a test email.</p>\",\"variables\":{\"variable_a_var\":\"Variable A Value\"},\"attachment\":[{\"name\":\"document.pdf\",\"url\":\"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf\"}],\"attachment_buffer\":[{\"name\":\"document.pdf\",\"content\":\"data:(mime type),base64,JVBERi0xLjQKJazc...\"}]}";
      try(OutputStream os = conn.getOutputStream()) {
          byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
          os.write(input, 0, input.length);
      }

      int code = conn.getResponseCode();
      System.out.println("Response code: " + code);
    }
  }

Send Transactional Email

Authorizations

Request Body required

Responses

201

Example

401

Example

402

Example

422

Example

451

Example

Examples

Request Body^required