POST
https://www.app.ocoya.com/api/_public/v1/email
Create a scheduled or a draft email
curl --request POST \
  --url https://www.app.ocoya.com/api/_public/v1/email \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "document": {
    "theme": {},
    "blocks": [
      {
        "type": "heading",
        "text": "Hi {{first_name}}",
        "level": 1
      },
      {
        "type": "text",
        "text": "Our autumn sale starts today."
      },
      {
        "type": "button",
        "label": "Shop now",
        "href": "https://example.com"
      }
    ]
  },
  "templateId": "launch",
  "name": "Autumn sale",
  "subject": "Our autumn sale starts today",
  "preheader": "<string>",
  "audience": {
    "groupIds": [
      "cmwdke1w70043y0k4ffzsa6om"
    ],
    "excludeGroupIds": []
  },
  "scheduledAt": "2024-01-01T00:00:00Z",
  "publishNow": false
}
'
{
  "emailId": "cmwdkjtfh005gy0k4ggzzg1bs",
  "status": "draft",
  "scheduledAt": null,
  "recipients": 120
}

Authorizations

X-API-Keystringheaderrequired

Your API key. Create one in Ocoya. Authorization: Bearer <key> works too.

Query Parameters

brandIdstringrequired

Ocoya brand ID. Get one from GET /brands.

Example:"cmayvq3hk00017apshay5qezu"

Body

application/json
documentobject

The email body.

Show child attributesHide child attributes
document.blocksobject[]required

The blocks, top to bottom. Common ones: {type: "heading", text, level}, {type: "text", text} (bold, italics and links in Markdown style), {type: "button", label, href}, {type: "image", src, alt, href}, {type: "hero", title, text, label, href, src}, {type: "divider"}, {type: "spacer", height}. Read any email with GET /email/{emailId} for the full format. Merge tags: {{first_name}}, {{last_name}}.

Example:
[
  {
    "type": "heading",
    "text": "Hi {{first_name}}",
    "level": 1
  },
  {
    "type": "text",
    "text": "Our autumn sale starts today."
  },
  {
    "type": "button",
    "label": "Shop now",
    "href": "https://example.com"
  }
]
Show child attributesHide child attributes
document.blocks.typestringrequired
document.themeobject

Fonts, colours and spacing. Left out: the brand's on create, the email's own on update.

templateIdstring

Template ID from GET /email/templates.

Example:"launch"
namestring
Example:"Autumn sale"
subjectstring
Example:"Our autumn sale starts today"
preheaderstring
audienceobject

Who gets it: subscribed contacts only, ever. Group IDs from GET /contacts/groups.

Show child attributesHide child attributes
audience.groupIdsstring[]

Send to contacts in any of these groups. Empty or left out: every subscribed contact.

Example:
[
  "cmwdke1w70043y0k4ffzsa6om"
]
audience.excludeGroupIdsstring[]

Leave out anyone in these groups.

Example:[]
scheduledAtstring

ISO 8601 datetime to send it at. Omit for a draft.

Example:"2024-01-01T00:00:00Z"
publishNowboolean

Send it to its whole audience at once.

Example:false

Response

application/json

Created

emailIdstring

ID of the email.

Example:"cmwdkjtfh005gy0k4ggzzg1bs"
statusenum<string>
Available options: generating, draft, scheduled, sending, sent, failed, canceled
Example:"draft"
scheduledAtstring | null
recipientsinteger

When it was scheduled or sent: how many contacts it goes to.

Example:120