Email¶

Before you begin¶

Prepare the recipient, sender, and content or template. This API permits one recipient in to; do not apply the SMTP recipient limit to this endpoint. When template_id is sent, body and subject are ignored.

Review Authentication and replace all example values, including template IDs and dates, before submitting a request.

Request workflow¶

Prepare the HTTP request shown below.
Complete the required fields and only the optional fields needed by your integration.
Submit the request and inspect its response.
Retain the returned identifier, when provided, and check the result before repeating a delivery.

HTTP request to send an email¶

POST https://send.obmessage.ai/api/v1/email
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{
    "to": [
        {
            "email": "string"
        }
    ],
    "options": {
        "cc": [
            {
                "email": "string"
            }
        ],
        "bcc": [
            {
                "email": "string"
            }
        ]
    },
    "from": {
        "email": "string",
        "name": "string"
    },
    "reply_to": {
        "email": "string",
        "name": "string"
    },
    "subject": "string",
    "body": "string",
    "attachments": [
        {
            "path": "string",
            "filename": "string"
        }
    ],
    "reference": "string",
    "group": "string",
    "template_id": "string",
    "not_sent_after": "string",
    "unsubscribe_group_id": 1,
    "fields": [
        {
            "name": "string",
            "value": "string",
            "short": true
        }
    ]
}

Note

The use of cc, bcc, and reply_to may not be available in all integrations. Contact technical support if you need to enable these options.

Important

Only one recipient can be sent in to. If more than one email is sent, the following error will be displayed:

{
    "code": "error.invalid_payload",
    "message": "cannot send email: currently only 1 'to.email' is allowed"
}

Field description¶

Required nested fields apply when their containing object or array element is included.

Field	Description	Required
to	Array of recipients.	Yes
to.email	Recipient email address.	Yes
options	Object used to include CC and BCC addresses.	No
options.cc	Email address of the copy recipient.	No
options.bcc	Email address of the blind copy recipient.	No
from	Sender information.	Yes
from.email	Sender email address. This field is optional if `from` is defined in the template.	No
from.name	Sender name.	No
reply_to	Information associated with message replies.	No
reply_to.email	Email address that will receive replies.	Yes
reply_to.name	Name associated with the reply address.	No
subject	Email subject.	No
body	Message content in HTML.	No
attachments	Array of URLs or base64 files to send as attachments.	No
attachments.path	File URL or base64 content.	Yes
attachments.filename	File name displayed in the delivery.	Yes
reference	Message reference ID.	No
template_id	ID of the created template. If this field is sent, `body` and `subject` are ignored.	No
not_sent_after	Any message processed after the specified time will be marked with the `cancelled` status. The time format must be `UTC`. This field is not required, but it is recommended to avoid sending notifications outside regulated hours. See the policies section.	No
group	Group reference ID for the message.	No
fields	Array of dynamic fields associated with the message.	No
fields.name	Field name.	Yes
fields.value	Field value.	Yes
fields.short	Indicates whether the field value should be shortened.	No
unsubscribe_group_id	ID of the unsubscribe group associated with the email sent.	No

Sample JSON payload¶

POST https://send.obmessage.ai/api/v1/email
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{
    "to": [
        {
            "email": "recipient@exampledomain.com"
        }
    ],
    "options": {
        "cc": [
            {
                "email": "cc@exampledomain.com"
            }
        ],
        "bcc": [
            {
                "email": "bcc@exampledomain.com"
            }
        ]
    },
    "from": {
        "email": "sender@yourdomain.com",
        "name": "Sender Name"
    },
    "subject": "Hello World",
    "body": "<h1>Hello World</h1>",
    "attachments": [
        {
            "filename": "reporte1.png",
            "path": "https://obmessage.ai/report.png"
        }
    ],
    "reference": "219012",
    "group": "campid01",
    "template_id": "4fefae9f-7259-4202-ac16-af18df821d74",
    "not_sent_after": "2024-02-12T23:30:59Z",
    "unsubscribe_group_id": 1,
    "fields": [
        {
            "name": "cuota",
            "value": "138.98"
        }
    ]
}

Try it in Postman

Response¶

The endpoint returns 200 OK with the following JSON response. Inspect status; this response alone does not confirm delivery to the recipient.

{
    "id": "string",
    "to": "string",
    "subject": "string",
    "reference": "string",
    "group": "string",
    "status": "string",
    "created_at": "string"
}

Response field description¶

Field	Description
id	Message identification code.
to	Message recipient, corresponding to the same value sent.
subject	Email subject, corresponding to the same value sent.
reference	Message reference ID, corresponding to the same value sent.
group	Group reference ID, corresponding to the same value sent.
created_at	Date when the message is received, in RFC 3339 format.
status	Current message status. Possible values are: `received` and `error`.

Unsubscribe¶

It is possible to enable an unsubscribe function so users can opt out of certain services.

To do this, create the unsubscribe_group in obm-app, including the following data: name, description, and footer. The footer must contain the text {{unsubscribe_link}}.

To send the unsubscribe group in a notification, add the unsubscribe_group_id field, whose value is obtained from the OBMessage platform. See the Sample JSON payload section.

Check results and errors¶

Use the returned id in Check status. Keep the reference and group used by your integration to locate the records. For unsuccessful requests, see Error responses.