●REST API

With the REST API, you can use mailing for email templating even if most of your app is not written in TypeScript or JavaScript.

Send and Render Emails●

Previews●

Lists/Members [Platform]●

API keys●

Mailing uses API keys to protect endpoints that consume limited resources (e.g. sending email with your transport).

To get an API key, set up a database and log in (recommended).

Or, you can make up your own key and assign it to the MAILING_API_KEY environment variable in your deployment environment.

You then pass your API key in each request with one of these methods:

• Include the API key in the request headers: X-API-KEY=...
• Include the API key as a query string parameter: ?apiKey=...

API Details●

All API endpoints expect the body to be a JSON string and the header Content-Type to be "application/json".

/api/render

Render a template and props to HTML.

Authentication

Authentication is is not required by default because this route does not send email.

To require authentication, set process.env.REQUIRE_API_KEY to "true". Then api/render will return 401 unless a valid API key is included in the request.

Request GET POST

• templateName: string – required if using template mode, must be the name of one of your templates.
• props: string[] – required if using template mode, must correspond to the props your template expects.

const response = await fetch("https://example.com/api/render", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "templateName": "myTemplate",
    "props": {
      "name": "Alex"
    },
  }),
});

Success response

Error responses

422 Unprocessable Entity
Content-Type: application/json

{
  "error": "props could not be parsed from querystring"
}

/api/sendMail

Send an email using your configured sendmail.

Authentication

An API key is required.

Request POST

You can either use /api/sendMail to render and send a template or to send raw html.

• templateName: string – Required if you want Mailing to render and send one of your templates.
• props: string[] – Required if using a template that expects props.
• from, to, subject, etc. – Standard sendMail options, see Calling sendMail.
• html: string – Rather than passing templateName and props, you can instead pass html as a string. This is useful if you're already rendering some HTML emails with another method.
• previewName: string – (optional) gets put on the Message object in the database so you have a category beyond templateName for the type of email being sent. Useful for segmenting analytics if the templateName is more general.

const response = await fetch("https://example.com/api/sendMail", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": "your-api-key"
  },
  body: JSON.stringify({
    "to": "to@example.com",
    "from": "you@example.com",
    "subject": "Hello world",
    "templateName": "myTemplate",
    "props": {
      "name": "Alex"
    }
  }),
});

Success response

{
  "result": {
    "accepted": ["to@example.com"],
    "rejected": [],
    "envelopeTime": 193,
    "messageTime": 549,
    "messageSize": 48249,
    "response": "250 Ok 0100154cef10a27-de64ec0b-3284-4189-803f-88101a6dc701-000000",
    "envelope": {
      "from": "you@example.com",
      "to": ["to@example.com"]
      },
    "messageId": "<50bf8e94-1951-91bf-0140-38342382405f@mailing.run>"
  }
}

Error responses

422 Unprocessable Entity
Content-Type: application/json

{
  "error": "sendMail couldn't find a subject for your email"
}