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.

MethodPathDescriptionExample
GET, POST/api/renderrender a template with props to HTMLLink
POST/api/sendMailsend an email

MethodPathDescriptionExample
GET/api/previewsreturns the list of previewsLink
GET/api/previews/[previewClass]/[previewFunction]returns the rendered previewLink

MethodPathDescription
GET/api/listsget all lists
POST/api/listscreate a new list
GET/api/lists/[listId]/membersget the members of a list
POST/api/lists/[listId]/membersadd a member to a list
GET/api/lists/[listId]/members/[memberId]get a list member's status
PATCH/api/lists/[listId]/members/[memberId]update a list member's status

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=...

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

StatusDescriptionJSON Response Body
200Successhtml: string – the rendered HTML mjmlErrors: string[] – MJML errors thrown during template rendering

Error responses

StatusDescriptionJSON Response Body
401Invalid API keyerror: string mjmlErrors: string[]
422Invalid requesterror: string mjmlErrors: string[]
500Internal server errorerror: string
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

StatusDescriptionJSON Response Body
200Successresult the return value from sendMail. The result type may vary based on your transport.
{
  "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

StatusDescriptionJSON Response Body
401Invalid API keyerror: string mjmlErrors: string[]
422Invalid requesterror: string mjmlErrors: string[]
500Internal server errorerror: string
422 Unprocessable Entity
Content-Type: application/json

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