Email API methods

Available API endpoints:

POST https://api.sidemail.io/v1/email/send — Send an email
POST https://api.sidemail.io/v1/email/search — Query emails
GET https://api.sidemail.io/v1/email/{id} — Retrieve an email
DELETE https://api.sidemail.io/v1/email/{id} — Delete an email

Email Object

An email object represents a single email sent or scheduled.

id (string): Unique identifier of the email.
projectId (string): Identifier of the project associated with the email.
automationId (string, optional): Identifier of the automation associated with the email.
messengerId (string, optional): Identifier of the messenger associated with the email.
toAddress (string): Recipient's email address.
fromName (string, optional): Sender's display name.
fromAddress (string): Sender's email address.
replyToName (string, optional): Display name for the reply-to address.
replyToAddress (string, optional): Reply-to email address.
subject (string): Subject of the email.
templateId (string, optional): Identifier of the template used.
templateName (string, optional): Name of the template used.
templateProps (object, optional): Key-value pairs for template variables.
status (string): Status of the email ("queued", "delivered", "open", "bounce", "error", "complaint", "suppressed", "scheduled")
isOpenTracked (boolean): Whether open tracking is enabled.
createdAt (string): ISO8601 date string when the email was created.
scheduledAt (string, optional): ISO8601 date string for scheduled delivery.
text (boolean, optional): Indicates if the email has plain text content.
htmlReferenceUrl (string, optional): URL to the HTML content of the email.
events (array, optional): List of events associated with the email (e.g., open, click).
- type (string): Type of the event.
- time (string): ISO8601 date string of the event.
- ipAddress (string, optional): IP address associated with the event.
- userAgent (string, optional): User agent associated with the event.
attachments (array, optional): List of attachments.
- id (string): Identifier of the attachment.
- name (string): Name of the attachment.
- size (number): Size of the attachment in bytes.
- contentType (string): MIME type of the attachment.
- fileUrl (string, optional): URL to download the attachment.

Send email

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

Note: Inside the Sidemail dashboard, you'll find pre-generated, ready-to-copy code examples for multiple languages, including PHP, Ruby, Python, cURL, and more. These examples are tailored to your specific email templates, so you can quickly copy, customize, and start sending emails with ease.

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.

headers object optional
Specify any custom headers of an email. Both key and value must be a string type.

Headers example:

"headers": { "CC": "cc@example.com" }

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 a 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.
paginationCursorPrev string A cursor for use in pagination to fetch the previous page of the list.
limit number The number of results to return per page. Must be between 1 and 100. Default is 20.
query object
- search string: A text search query to match against email fields.
- toAddress string: Recipient's email address.
- fromName string: Sender's display name.
- fromAddress string: Sender's email address.
- subject string: Subject of the email.
- templateName string: Name of the template used.
- templateId string or array: Identifier(s) of the template(s) used.
- automationId string or array: Identifier(s) of the automation(s) associated with the email.
- messengerId string or array: Identifier(s) of the messenger(s) associated with the email.
- status string or array: Status of the email (e.g., "queued", "delivered", "open").
- scheduledAt date: ISO8601 date string for scheduled delivery.
- templateProps object: Key-value pairs to match against template variables.

Returns

A response 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.

{
    hasPrev: true,
    hasMore: true,
    paginationCursorPrev: "307f1f70bcf86cd799439011",
    paginationCursorNext: "407f1f70bcf86cd799439011",
    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
}