Email¶

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¶

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¶

If the message is sent successfully, the API returns 200 OK with the following JSON payload:

{
    "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.