Email API methods

Available API endpoints:

  • POST https://api.sidemail.io/v1/email/send
  • GET https://api.sidemail.io/v1/email/{id}
  • DELETE https://api.sidemail.io/v1/email/{id}

Send email

POST https://api.sidemail.io/v1/email/send

Node.js example:

const configureSidemail = require("sidemail");
const sidemail = configureSidemail({ apiKey: "replace-with-your-api-key" });
  
const response = await sidemail.sendEmail({
	toAddress: "user@email.com",
	fromAddress: "you@example.com",
	fromName: "Your app",
	templateName: "Welcome",
});

Parameters

toAddress string
A valid email email address that will receive the email.

  • Only ASCII characters are supported.

For multiple recipients, CC (Carbon Copy), or BCC (Blind carbon copy), use batch email sending which lets you send up to 50 emails in a single HTTP API request.


subject string
An email subject line.

  • All UTF-8 characters (emojis are supported).

fromName string optional
Display name (also known as friendly name) that appears before the fromAddress email address.

For example: Sidemail or Patrik from Sidemail.

  • It has to have at least 1 character and less than 100 characters.
  • All UTF-8 characters (emojis are supported).

fromAddress string
The email address from which you want to send the email.

For example: info@sidemail.io.

To define a display name (a name before the actual email address), usefromName.


replyToAddress string optional
If you want the recipient of an email to reply to a different email address than fromAddress, specify it with replyToAddress.

  • Only ASCII characters are supported.

templateId string optional
A template ID of the template you want to send.

Cannot be used together with templateName, html or text.


templateName string optional
A template name of the template you want to send.

Cannot be used together with templateId, html or text.


templateProps object optional
Pass data to template props here. Use exactly the same key name (whitespace sensitive) as you did in your email template. If a variable has been defined in your email template, but you didn't add it to templateProps when making an API request, the key name of the variable will be used as a fallback.​

For example: if you defined {firstName} template prop inside of the email template you want to send, the templateProps parameter should include a key firstName with a value that is string.

{
    "firstName": "Patrik"
}

Learn more about dynamic data with template props.


html string optional
To send your own HTML email, pass your HTML as a string into the html parameter.

  • You can't combine it with templateId or templateName.

Sidemail does not inline CSS, or process the custom HTML email in any other way. Do any processing in your application before sending if necessary.

Learn more about sending custom HTML emails.


text string optional
To send a plain-text email, pass string into the text parameter.

  • Combine with html to create both plain-text and HTML version of your email.
  • You can't combine it with templateId or templateName.

Learn more about sending plain-text emails.


isOpenTracked boolean optional
Whether the email should be open tracked or not.

  • Default is true — emails are open tracked by default.

scheduledAt date optional
Specify a delayed email delivery by providing a valid ISO 8601 date in the future.

Learn more about scheduled email delivery.


Returns

Returns an object with an email ID and the current status on success.

{
  "id": "5e858953daf20f3aac50a3da",
  "status": "queued"
}

When sending a batch of emails in a single API call, it returns an ordered array of objects with email ID and the current status on success:

[
    {
        id: "5e858953daf20f3aac50a3da",
        status: "queued",
    },
    {
        id: "6e858953daf20f3aac50a3da",
        status: "queued",
    },
];

Retrieve email

GET https://api.sidemail.io/v1/email/{id}

Retrieves the email data. You need only supply the email ID to the URL.

Parameters

No parameters.

Returns

Returns an email object if email was found or null.

{
    email: {
        "id": "307f1f70bcf86cd799439011",
        "projectId": "507f1f77bcf86cd799439011",
        "toAddress": "marry@lightling.com",
        "fromAddress": "hey@sidemail.io",
        "fromName": "Sidemail",
        "subject": "Some email subject",
        "templateId": "192f1f77bcf86cd799439011",
        "templateName" "Welcome",
        "templateProps": [{ "keyName": "name", "value": "Marry" }],
        "status": "delivered",
        "isOpenTracked": true,
        "createdAt": "2019-08-15T13:20:39.160Z"
    }
}

Delete email

Permanently deletes an email. It cannot be undone. Only scheduled emails which are yet to be send can be deleted.

Parameters

No parameters.

Returns

Returns an object with deleted parameter that indicates the outcome of the operation.

{
    "deleted": true
}