Email API methods

Available API endpoints:

POST https://api.sidemail.io/v1/email/send
POST https://api.sidemail.io/v1/email/search
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.

Only verified sending domains or pre-generated by Sidemail
Only ASCII characters are supported.

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

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 or markdown.

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

Cannot be used together with templateId, html or text or markdown.

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.

markdown string optional
To send markdown content which Sidemail turns into branded transactional email, pass the markdown as a string into the markdown parameter.

Cannot be used together with templateId or templateName or html or text.
Must be less than 102 400 characters long (100 kB).

Learn more about sending markdown content →

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

Cannot be used together with templateId or templateName or markdown.
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).
Due to potential for abuse, new accounts created after January 30, 2023 must be manually approved to send custom HTML emails. Don't hesitate to contact us at support@sidemail.io to get approved with legitimate use cases.

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.
Cannot be used together with templateId or templateName or markdown.
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",
    },
];

Search emails

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

Searches emails based on the provided query and returns found email data. This endpoint is paginated and it returns maximum of 20 results per page. The email data are returned sorted by creation date, with the most recent emails appearing first.

To list emails without any filter, exclude the query from the JSON payload.

JSON payload example:

{
    "query": {
        "toAddress": "john.doe@example.com",
        "status": "delivered",
        "templateProps": {
            "color": "red"
        }
    }
}

Parameters

paginationCursorNext string A cursor for use in pagination. paginationCursorNext is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with obj_foo, your subsequent call can include paginationCursorNext=obj_foo in order to fetch the next page of the list.

query object

toAddress string
fromName string
fromAddress string
subject string
templateName string
templateId string
status string
- Valid values: queued, scheduled, error, suppressed, bounce, complaint, delivered
scheduledAt date
templateProps object
- Any string key value pair in templateProps to search.

Returns

A object with a data property that contains an array of up to 20 emails. Each entry in the array is a separate email object. If no more emails are available, the resulting array will be empty.

{
    hasMore: true,
    paginationCursorNext: "307f1f70bcf86cd799439011",
    data: [
        {
            "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": null,
        },
        // Another 19 found emails...
    ]
}

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
}