email-send - GMS for Developers

Sends an email or a bunch of emails.

https://dns-name/email/send

While sending you can provide substitutions (merge tags), use a template, turn on read or click tracking, etc.

Restrictions:

maximum request size is 10 MB
maximum number of recipients is 500
The symbol ‘/’ is not allowed in attachment names

If the list of recipients contains invalid, non-existent, duplicate, or unsubscribed emails, those emails will be returned in the output parameter failed_emails, and the email will be sent to all other valid emails addresses. If all the emails addresses fall into failed_emails, sending will not be carried out and API error 204 will be returned.

Request Body

POST https://dns-name/email/send
Content-Type: application/json
X-API-KEY: Value

{
  "request": {
    "recipients": [
      {
        "email": "string",
        "replacements": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "info": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      }
    ],
    "body": {
      "html": "string",
      "plaintext": "string",
      "amp": "string"
    },
    "subject": "string",
    "headers": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "attachments": [
      {
        "type": "string",
        "name": "string",
        "content": "string"
      }
    ],
    "options": {
      "send_at": "string",
      "unsubscribe_url": "string",
      "custom_backend_id": 0,
      "smtp_pool_id": "string"
    },
    "template_id": "string",
    "skip_subscription": 0,
    "main_language": "string",
    "template_creator": "string",
    "global_replacements": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "global_info": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "sender_email": "string",
    "sender_name": "string",
    "reply_to": "string",
    "check_links": 0,
    "check_read": 0,
    "inline_attachments": [
      {
        "type": "string",
        "name": "string",
        "content": "string"
      }
    ]
  }
}

Request Parameters


request	OBJECT Required	Object containing all request properties
»recipients	ARRAY Required	Contains recipient emails, substitutions (merge tags) and metadata
»»email	String Required	Recipient email
»»replacements	OBJECT	Object to pass the replacements(merge tags) for the recipient (e.g. recipient name, discount code, password change link, etc). The substitutions can be used in the following parameters: – body.html – body.plaintext – body.amp – subject – sender_name – headers[“List-Unsubscribe”] – options.unsubscribe_url A substitution name can consist from latin characters, numbers and “_” or “-” symbols, and should start with the letter.
»»info	OBJECT	Object for passing the info, such as “key”: “value”. Max key quantity: 10. Max key length: 64 symbols. Max value length: 1024 symbols. The info is returned by our webhook on your provided endpoint. If you pass unsigned decimal integer up to 128 bit with “campaign_id” field name (name is configurable thru support), it will be considered as campaign identifier in statistics.
»template_id	String (UUID)	Optional identifier of the template that had been created by TEMPLATE-SET method. If template_id is passed then fields from the template are used instead of missed EMAIL-SEND parameters. E.g. if “body” parameter in EMAIL-SEND is omitted, “body” from template will be used. If “subject” in EMAIL-SEND is omitted, “subject” from template will be used.
»skip_subscription	INTEGER	Whether to skip or not appending default unsubscribe footer. 1=skip, 0=append, default is 0. You should GMS Support to approve.
»main_language	STRING	The language of the unsubscribe footer and unsubscribe page. Languages supported are: “be”, “de”, “en”, “es”, “fr”, “it”, “pl”, “pt”, “ru”, “ua”.
»template_builder	STRING	Editor type, “html” or “visual”. Default is “html”. You can create a template with “visual” editor type only in web interface.
»global_replacements	OBJECT	Object for passing the substitutions(merge tags) common for all recipients – e.g., company name. If the substitution names are duplicated in object “substitutions”, the values of the variables will be taken from the object “substitutions”. The substitutions can be used in the following parameters: – body.html – body.plaintext – body.amp – subject – sender_name – options.unsubscribe_url A substitution name can consist from latin characeters, numbers and “_” or “-” symbols, and should start with the letter.
»global_info	OBJECT	Object for passing the info common for all the recipients, such as “key”: “value”. Max key quantity: 10. Max key length: 64 symbols. Max value length: 1024 symbols. The metadata is returned by webhook on your endpoint.
»body	OBJECT REQUIRED	Contains HTML/plaintext/AMP parts of the email. Either html or plaintext part is required.
»»html	STRING	HTML part of the email body
»»plaintext	STRING	Plaintext part of the email body
»»amp	STRING	Optional AMP part of the email body
»subject	STRING	Email subject
»sender_email	STRING	Sender’s email. Required only if template_id parameter is empty.
»sender_name	STRING	Sender’s name
»reply_to	STRING	Optional Reply-To email (in case it’s different to sender’s email)
»check_links	INTEGER	1=click tracking is on (default), 0=click tracking is off
»check_read	INTEGER	1=read tracking is on (default), 0=read tracking is off
»headers	OBJECT	Contains email headers, maximum 50. Only headers with “X-” name prefix are accepted, all other are ignored, for example X-GMS-Global-Language, X-GMS-Template-Engine.
»attachments	ARRAY	Optional array of attachments
»»type	STRING REQUIRED	Attachment type, see MIME. If unsure, use “application/octet-stream”.
»»name	STRING REQUIRED	Attachment name in the format: “name.extension” Attachment content id. For example, “name”=“IMAGECID1” should be referenced in HTML like <img src=“cid:IMAGECID1”>
»»content	STRING (BYTE) REQUIRED	File contents in base64. Maximum file size 7MB (9786710 bytes in base64).
»inline_attachments	ARRAY	Optional array of inline attachments, e.g. for including images in email instead of loading them from external URL
»options	OBJECT	Additional message options
»»send_at	STRING	Date and time in “YYYY-MM-DD hh:mm:ss” format in the UTC timezone. Allows schedule sending up to 24 hours in advance.
»»unsubscribe_url	STRING	Custom unsubscribe link

Response Body

{
  "status": "string",
  "emails": [
    "string"
  ],
  "job_id": "string",
  "failed_emails": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

HTTP Code 200:

Email successfully accepted for sending

Response Parameters

Name	Type	Description
status	STRING REQUIRED	“Success” string
job_id	STRING REQUIRED	Job identifier, might be useful for investigating errors
emails	ARRAY	Array of recipients emails successfully accepted for sending
failed_emails	OBJECT	Object with emails rejected for sending as property names and their statuses as property values, e.g.: {“email1@gmail.com”: “temporary_unavailable”}. Possible statuses: – unsubscribed: specified email is unsubscribed; – invalid: the email does not exist or has been entered incorrectly; – duplicate: the email already exists in the request, email duplicating is prevented; – temporary_unavailable: the email address is unavailable. This means that over the next three days sending to this address will return an error. Email may be temporarily unavailable due to several reasons, e.g.: a. a previous email has been rejected by the recipient’s server for spam; b. the recipient’s mailbox is full or is not used; c.recipient’s domain does not accept mail; d. sending server was rejected due to blacklisting; – permanent_unavailable: the email address is permanently unavailable or unsubscribed globally. – complained: the recipient reported spam in the previous emails; – blocked: sending to the email is prohibited by administration of UniOne. We may added new statuses in the future.

{
  "status": "string",
  "code": 0,
  "message": "string"
}

HTTP Code default:

Error occurred

Name	Type	Description
status	STRING REQUIRED	“Error” string
message	STRING REQUIRED	Human-readable error message in English
code	INTEGER REQUIRED	API Error code