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.

replyToName string optional
Use in conjunction with replyToAddress to show a friendly name for the replyToAddress. Ignored if replyToAddress is not specified.

  • It has to have at least 1 character and less than 100 characters.
  • All UTF-8 characters (emojis 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.
  • Must be less than 1 024 000 characters long (1000 kB). Note that Gmail cuts off email preview if longer than 104 448 characters (102 kb).

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.
  • Must be less than 102 400 characters long (100 kB).

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.


attachments array optional

Attach a Base64 encoded file to an email.

  • The attachments array must contain a valid attachment object (described below).
  • The attachments array can contain multiple attachment objects.
  • The combined file size limit is 2500 kB (which is equal to less than 2 621 440 characters long). Note that file size is calculated from the Base64 encoded string, which is on average 133% of the original file size.
  • Allowed files: .jpg .pdf .csv .html .png .gif .json .txt

attachment object required

  • name string required

    The name of the attached file that will show up to the recipient.

    • The file ending must be one of the allowed file types (as described above).
    • Must be less than 100 characters long.
    • Must contain at least 1 character before a valid file ending.
    • The content type is set automatically based on the file ending.
  • content string required

    The Base64 encoded file.

    • Must be valid Base64 (RFC 4648)
    • Must be less than 2 621 440 characters long (2500 kB).

Attachment example:

{
  "attachments": [
    {
      "name": "file.txt",
      "content": "dmFsaWQgY29udGVudA=="
    }
  ]
}

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",
        "attachments": [
            { 
                "id": "907f1f77bcf86cd799439011", 
                "name": "invoice.txt", 
                "size": 51200
            }
        ]
    }
}

Delete email

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

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
}