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.

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