POST /mail/v2/send

Send a transactional email to up to 100 recipients in a single request. Each recipient carries its own personalization data, so a single call can deliver a genuinely different, personalized email to each person in the batch.

Endpoint and headers

POST https://email.useinsider.com/mail/v2/send

Body parameters

Below are the body parameters for this request.

* Each recipient must have at least one of email or UUID.
** Provide either content or template_id, exactly one. Sending both is rejected with 400.
Attachments: Each item has content (base64), file_name, optional disposition (attachment by default, or inline for embedded images), optional content_id (the CID an inline image is referenced by), and optional content_type.

Request examples

Send each JSON body with the headers above.

Personalized order confirmation, with an item list and attachment

{
  "subject": "Order {{ order.id }} confirmed",
  "from": {
    "email": "no-reply@acme.com",
    "name": "Acme Store"
  },
  "recipients": [
    {
      "email": "alice@example.com",
      "name": "Alice",
      "fields": {
        "first_name": "Alice",
        "order": {
          "id": "A-1024",
          "total": "129.90",
          "items": [
            {
              "qty": 1,
              "name": "Wireless Mouse"
            },
            {
              "qty": 2,
              "name": "USB-C Cable"
            }
          ]
        }
      }
    }
  ],
  "content": [
    {
      "type": "text/html",
      "value": "<p>Hi {{ first_name }}, order {{ order.id }} ({{ order.total }}) is confirmed.</p>{% for item in order.items %}<p>{{ item.qty }} x {{ item.name }}</p>{% endfor %}"
    }
  ],
  "category": 3,
  "attachments": [
    {
      "content": "aW52b2ljZV9jb250ZW50",
      "file_name": "invoice.pdf"
    }
  ]
}

Multiple recipients, each personalized

{
  "subject": "Your order {{ order.id }} has shipped",
  "from": {
    "email": "no-reply@acme.com",
    "name": "Acme Store"
  },
  "recipients": [
    {
      "email": "alice@example.com",
      "fields": {
        "first_name": "Alice",
        "order": {
          "id": "A-1024",
          "tracking": "TRK-111"
        }
      }
    },
    {
      "email": "bob@example.com",
      "fields": {
        "first_name": "Bob",
        "order": {
          "id": "A-1025",
          "tracking": "TRK-222"
        }
      }
    }
  ],
  "content": [
    {
      "type": "text/html",
      "value": "<p>Hi {{ first_name }}, order {{ order.id }} is on its way. Track it: {{ order.tracking }}</p>"
    }
  ]
}

Recipient by UUID (email resolved automatically)

{
  "subject": "Your password was reset",
  "from": {
    "email": "security@acme.com",
    "name": "Acme Security"
  },
  "recipients": [
    {
      "uuid": "9f8b7c6d-1234-4a2b-9c3d-abcdef012345",
      "fields": {
        "first_name": "Alice"
      }
    }
  ],
  "content": [
    {
      "type": "text/html",
      "value": "<p>Hi {{ first_name }}, your password was just changed.</p>"
    }
  ],
  "category": 7
}

Conditional content with Liquid

A free shipping line appears only for orders over 100.

{
  "subject": "Order {{ order.id }} confirmed",
  "from": {
    "email": "no-reply@acme.com",
    "name": "Acme Store"
  },
  "recipients": [
    {
      "email": "alice@example.com",
      "fields": {
        "first_name": "Alice",
        "order": {
          "id": "A-1024",
          "total": 129.9
        }
      }
    }
  ],
  "content": [
    {
      "type": "text/html",
      "value": "<p>Hi {{ first_name }}, order {{ order.id }} is confirmed.</p>{% if order.total > 100 %}<p>You qualified for free shipping!</p>{% endif %}"
    }
  ]
}

HTML and plain-text body

{
  "subject": "Order {{ order.id }} confirmed",
  "from": {
    "email": "no-reply@acme.com",
    "name": "Acme Store"
  },
  "recipients": [
    {
      "email": "alice@example.com",
      "fields": {
        "first_name": "Alice",
        "order": {
          "id": "A-1024"
        }
      }
    }
  ],
  "content": [
    {
      "type": "text/html",
      "value": "<p>Hi {{ first_name }}, order {{ order.id }} is confirmed.</p>"
    },
    {
      "type": "text/plain",
      "value": "Hi {{ first_name }}, order {{ order.id }} is confirmed."
    }
  ]
}

Inline image (CID) and PDF attachment

Embed a logo with disposition: inline and a content_id, then reference that id from an HTML image element whose source is cid:acme-logo. In the body below, replace [image element with source cid:acme-logo] with a standard HTML image tag.

{
  "subject": "Your invoice for order {{ order.id }}",
  "from": {
    "email": "billing@acme.com",
    "name": "Acme Billing"
  },
  "recipients": [
    {
      "email": "alice@example.com",
      "fields": {
        "first_name": "Alice",
        "order": {
          "id": "A-1024"
        }
      }
    }
  ],
  "content": [
    {
      "type": "text/html",
      "value": "[image element with source cid:acme-logo]<p>Hi {{ first_name }}, your invoice is attached.</p>"
    }
  ],
  "attachments": [
    {
      "content": "iVBORw0KGgo...",
      "file_name": "logo.png",
      "disposition": "inline",
      "content_id": "acme-logo",
      "content_type": "image/png"
    },
    {
      "content": "aW52b2ljZV9jb250ZW50",
      "file_name": "invoice.pdf",
      "disposition": "attachment",
      "content_type": "application/pdf"
    }
  ]
}

Using a saved template (template_id)

When template_id is set, the HTML is fetched from the Email Template Library, and the content is omitted. Personalization still comes from each recipient's fields.

{
  "subject": "Welcome, {{ first_name }}",
  "from": {
    "email": "no-reply@acme.com",
    "name": "Acme Store"
  },
  "template_id": "welcome-series-01",
  "recipients": [
    {
      "email": "alice@example.com",
      "fields": {
        "first_name": "Alice"
      }
    }
  ],
  "unique_args": {
    "transaction_type": "welcome"
  }
}

Sample response

A successful send returns 202 Accepted with a message_id. Use that ID with the delivery-status endpoint to track progress.

{
  "status": "accepted",
  "message_id": "550e8400-e29b-41d4-a716-446655440000"
}

For duplicate, validation, and other error responses, refer to the Error Codes.

Error reference

Use this table to identify and resolve the responses this endpoint returns. Each row shows the status code, the response body you receive, what causes it, and how to fix it. For the shared reference covering every endpoint in this category, see Transactional Email Error Codes.

Validation rules

The following rules are enforced and reported through the validation failed response.

Required fields

• subject

• from.email, and the sender domain must be authenticated

• recipients, at least one entry

• exactly one of content or template_id

• each recipient must carry email or uuid

• each content block needs a non-empty value

Format and content rules

• content[].type must be text/html or text/plain, each at most once.

• A text/html block is mandatory. A plain-text-only send is rejected.

• subject and content[].value are rejected if they contain script, iframe, or inline event-handler markup.

• Every email field must be a valid address. The accepted top-level domain is 2 to 10 letters.

• The same address may not appear twice within recipients, cc, or bcc, nor across two of those lists.

• attachments[].content must be valid base64, file_name is required, and disposition must be attachment or inline.

• campaign_id may not contain control characters or a colon.

• fields must be JSON-serializable.

Keep in mind

• Personalization is explicit. All Liquid variables must be included in each recipient's fields. Attributes stored in a user's profile are not automatically pulled into the template.

• UUID resolution. A recipient given by UUID is resolved to an email through a profile lookup during processing. If no email is found, that recipient is dropped, and the rest of the send proceeds. This lookup resolves only the email address.

• Transactional only. These emails do not carry a promotional unsubscribe link or List-Unsubscribe header. Transactional mail is one-to-one and must not carry promotional unsubscribe links.

Limitations