Skip to main content
POST
AhaSend Go SDK
The AhaSend API creates one account-global contact. Access requires contacts:write. Only email is required. The API trims it and changes it to lowercase. An email address that another contact of the account already has is refused with 409. Fields:
  • status is enabled when you leave it out or send null.
  • unsubscribed: true creates the contact as unsubscribed account-wide, and sets unsubscribed_at to the current UTC time. Campaigns do not send to an unsubscribed contact.
  • attributes must use the keys and types that you defined in the dashboard, and a value cannot be null. See Attributes.
  • validation_status and last_validated_at are read-only.
The new contact is on no list, so a campaign cannot reach it yet. To add it to a list, use Add or Update a List Contact or Batch Add List Contacts. Create Contact does not read or change suppressions. This operation accepts an Idempotency-Key header. The API stores a 201, a 400 and a 409 for a duplicate contact for 24 hours, and replays them for a retry with the same key. A 409 with Idempotent-Replayed: false and Retry-After means a request with the same key is still in progress. See Idempotency.

Authorizations

Authorization
string
header
required

API key for authentication. Non-empty Security Requirement values are AhaSend API-key roles. Roles listed within one requirement object are jointly required; separate requirement objects are alternatives.

Scopes

contacts:write

Headers

Idempotency-Key
string

Optional idempotency key for safe request retries. Must be a unique string for each logical request. An identical request with a completed stored outcome returns the original status and body. An in-progress execution returns 409, a changed method/path/body returns 422, and a released 5xx execution may run again. Keys for non-secret responses expire after 24 hours. API-key create responses include a one-time secret_key, so successful encrypted replay responses for those operations expire after 5 minutes.

Maximum string length: 255

Path Parameters

account_id
string<uuid>
required

Account ID

Body

application/json

Creates an account-global contact without list membership. Writable attribute keys and types are derived from definitions managed in the dashboard. Validation metadata, membership, and activity are not writable.

email
string<email>
required

Contact email; trimmed and lowercased before persistence

first_name
string | null
last_name
string | null
status
enum<string> | null

Defaults to enabled when omitted or null

Available options:
enabled,
disabled,
blocked,
null
status_reason
string | null
unsubscribed
boolean | null

Only true creates an initial UTC unsubscription timestamp

attributes
object | null

Values are validated against dashboard-managed account attribute definitions. Attribute members cannot be null.

Response

Contact created successfully

Public contact projection. Attribute values can be null, booleans, numbers, strings, arrays, or nested objects, even though writes accept only canonical dashboard-defined values.

object
enum<string>
required

Object type identifier

Available options:
contact
id
string<uuid>
required

Unique identifier for the contact

created_at
string<date-time>
required

When the contact was created

updated_at
string<date-time>
required

When the contact was last updated

email
string<email>
required

Normalized contact email address

first_name
string
required
last_name
string
required
status
enum<string>
required
Available options:
enabled,
disabled,
blocked
status_reason
string
required
unsubscribed
boolean
required
unsubscribed_at
string<date-time> | null
required
attributes
object
required
validation_status
enum<string>
required
Available options:
unvalidated,
valid,
invalid,
risky,
unknown
last_validated_at
string<date-time> | null
required